slugid generator

Slugid is a compact identifier format that encodes standard UUIDs into 22-character, URL-safe strings using base64url encoding. The format was created at Mozilla as part of the TaskCluster project, a continuous integration and task execution framework that powers Firefox's build and release infrastructure. TaskCluster needed identifiers that were globally unique (like UUIDs), short enough to use comfortably in URLs and file paths, safe for use without percent-encoding in web contexts, and fully reversible back to standard UUIDs for compatibility with systems that expect RFC 4122 format. Slugid met all of these requirements by applying the base64url encoding defined in RFC 4648 to the raw 16-byte UUID value, producing a fixed-length 22-character string that carries the full 128-bit UUID payload without information loss.

The name "slugid" combines "slug" (a URL-friendly string) with "id" (identifier), reflecting its primary purpose: turning UUIDs into URL slugs. Unlike approaches that generate new identifier formats, Slugid is a pure encoding transformation. Every Slugid corresponds to exactly one UUID, and every UUID can be encoded as exactly one Slugid. This bidirectional mapping means Slugid can be adopted incrementally in systems that already use UUIDs, serving as an interchangeable representation rather than a migration. The library was initially implemented in JavaScript for TaskCluster's web interfaces, with ports since created in Python, Go, and other languages.

How Slugid Works

A UUID is a 128-bit (16-byte) value. In standard textual form, these bytes are encoded as 32 hexadecimal characters with hyphens forming the 8-4-4-4-12 pattern, producing a 36-character string like f47ac10b-58cc-4372-a567-0e02b2c3d479. This encoding is inefficient because each character represents only 4 bits and the hyphens carry no information.

Slugid applies base64url encoding to the raw 16-byte binary UUID value. Base64url uses a 64-character alphabet consisting of uppercase letters (A-Z), lowercase letters (a-z), digits (0-9), hyphen (-), and underscore (_). Each character in base64 represents 6 bits of information, compared to 4 bits in hexadecimal. Encoding 128 bits in base64 produces ceil(128/6) = 22 characters, with 4 bits of padding. Standard base64 would append padding characters (=) to make the output length a multiple of 4, resulting in a 24-character string with two trailing equals signs. Slugid strips these padding characters because they are unnecessary for decoding when the original data length (16 bytes) is known, yielding the final 22-character output.

The base64url variant is specifically chosen over standard base64 because it replaces the plus (+) and slash (/) characters with hyphen (-) and underscore (_). This substitution is critical for URL safety: plus signs are interpreted as spaces in URL query strings, and slashes are path separators. By using only characters with no special meaning in URLs or file systems, Slugid values can be used directly in URLs, file names, and command-line arguments without escaping.

The Slugid library provides two generation modes. The standard slugid() function generates a new UUID v4 and encodes it as a Slugid. The nice() function also generates a UUID v4 but ensures the first character is always a letter from the range A-Q, guaranteeing the Slugid can be used in contexts requiring identifiers that begin with a letter (such as programming language identifier rules or certain database systems). This is achieved by constraining the most significant bits of the UUID.

The decoding process is the exact reverse: take the 22-character Slugid string, append the two padding characters (==), decode from base64url to obtain 16 bytes, and format those bytes as a standard UUID string with hyphens. This round-trip is lossless and deterministic, meaning decode(encode(uuid)) === uuid always holds, and encode(decode(slugid)) === slugid likewise.

Use Cases

Continuous integration and build systems. Slugid's original use case remains one of its strongest. In CI/CD systems like TaskCluster, each task, artifact, and worker is identified by a unique ID that appears in URLs, log files, and API responses. Using full UUIDs creates unwieldy URLs and cluttered logs. Slugid reduces a 36-character UUID to 22 characters while preserving the ability to look up the corresponding UUID in backend systems. The URL-safety guarantee means task IDs can be embedded directly in webhook URLs and API endpoints without encoding.

File and directory naming. When unique identifiers are used as file names or directory names, URL-safe characters are essential to avoid cross-platform compatibility issues. Slugid values contain no characters that are problematic on Windows, Linux, or macOS file systems, and their fixed 22-character length makes them predictable for file system operations. This is useful for temporary file management, cache key generation, and artifact storage systems where each file corresponds to a unique operation or entity.

Short URL identifiers and routing tokens. Web applications that need to embed unique identifiers in URLs benefit from Slugid's compactness. A URL like /tasks/WIGkRM-hQrSAyhst0cXBVA is significantly cleaner than /tasks/5882047c-e1e4-42b4-8021-b2d1c5c15405. The 22-character length is short enough for practical use in QR codes, email links, and printed materials while still carrying the full 128-bit uniqueness of a UUID v4. For applications that later need to transition to standard UUID display (for example, in administrative interfaces or database queries), the Slugid can be decoded without any lookup table.

Cross-system identifier bridging. In architectures where some systems use UUIDs and others have identifier format constraints, Slugid serves as an effective bridge. An upstream system can generate UUIDs, encode them as Slugids for transmission through constrained channels, and the downstream system can use the Slugid directly or decode it back to a UUID. This is useful in message queues, webhook payloads, and configuration files where format constraints vary between components.

Comparison with Alternatives

Short-UUID and Slugid solve the same problem -- compressing UUIDs into shorter strings -- but differ in encoding approach. Short-UUID uses a customizable alphabet (defaulting to base57 with ambiguous characters removed) via arbitrary-precision integer division. Slugid uses standardized base64url. Both produce 22-character strings, but Slugid can be decoded using any base64url implementation without the library itself. Short-UUID requires its specific base conversion logic for decoding. If interoperability with standard tools is a priority, Slugid has an advantage. If you need to exclude ambiguous characters for human readability, Short-UUID's base57 default is more suitable.

Compared to UUID in its standard representation, Slugid's advantage is purely in compactness and URL safety. A Slugid is 22 characters versus a UUID's 36 characters, a 39% reduction. Both carry identical information, and conversion between them is trivial. The choice is a presentation-layer decision with no impact on uniqueness or correctness. In systems where UUID format is expected by external partners or compliance requirements, use UUIDs directly. In internal systems and URLs where brevity matters, Slugid provides a meaningful improvement.

Nano ID represents a fundamentally different approach. Nano ID generates new random strings using a cryptographically secure generator and a customizable alphabet, producing identifiers that are not based on UUIDs and cannot be converted to or from them. Nano ID's default 21-character output is one character shorter than a Slugid, but Nano ID values are opaque random strings with no underlying structure. If your system depends on UUIDs for database storage, API contracts, or cross-service compatibility, Slugid preserves that dependency while Nano ID breaks it. If you have no UUID requirement, Nano ID is simpler and more direct.