@pfarr.tools/slug

German-aware URL slug generator, compatible with Laravel's Str::slug().

Converts German umlauts and ligatures before general Unicode normalization, producing slugs that match what a German speaker would expect: Über → ueber, Straße → strasse.

Installation

npm install @pfarr.tools/slug

Usage

ESM

import { slug } from '@pfarr.tools/slug';

slug('Ärger mit Öl');        // 'aerger-mit-oel'
slug('Über den Wolken');     // 'ueber-den-wolken'
slug('café au lait');        // 'cafe-au-lait'
slug('Hello, World!');       // 'hello-world'
slug(null);                  // ''

CommonJS

const { slug } = require('@pfarr.tools/slug');

Default export

import slug from '@pfarr.tools/slug';

API

slug(input)

Returns string — lowercase slug containing only [a-z0-9-], or '' for null/undefined.

Conversion pipeline

1. null/undefined → return ''
2. Coerce to string
3. German transliteration: Ä→Ae, Ö→Oe, Ü→Ue, ä→ae, ö→oe, ü→ue, ß→ss
4. Unicode NFD normalization + strip combining diacriticals (é→e, ñ→n, ç→c, …)
5. Lowercase
6. Replace runs of non-[a-z0-9] characters with -
7. Strip leading/trailing -
8. Collapse consecutive -

Examples

slug('Größe & Stärke');           // 'groesse-staerke'
slug('Straße des 17. Juni');      // 'strasse-des-17-juni'
slug('  --leading and trailing--  '); // 'leading-and-trailing'
slug('Chapter 3: The Beginning'); // 'chapter-3-the-beginning'
slug(2024);                       // '2024'
slug('already-clean-slug');       // 'already-clean-slug'

Compatibility with Laravel Str::slug()

This function mirrors the behaviour of Laravel's Str::slug() for German input. Laravel uses Str::ascii() internally, which applies the same umlaut→digraph mapping. The separator is always - (the Laravel default).

License

GPL-3.0-or-later — © Christoph Fischer chris@toph.de