cuid2

Cuid2 is a next-generation unique ID generator built as a security-conscious replacement for UUIDs and the original Cuid. Instead of relying on a single entropy source, it combines the current timestamp, a session counter, a host fingerprint, and cryptographically secure random values, then mixes them through a NIST-standard SHA3 hash so the output reveals nothing about how or when it was created.

The library ships as a tiny, dependency-light ESM package with zero async operations, making it safe to call in hot paths across Node.js and browser environments. It also includes a CLI (npx @paralleldrive/cuid2) for generating ad-hoc IDs and slugs from the terminal, and an isCuid validator for checking existing values. With over 19 million weekly downloads, it’s a common choice for primary keys, request IDs, and other identifiers that need to be generated client-side without a database round trip.

What You Get

• createId() — a zero-config function that returns a 24-character, lowercase alphanumeric identifier ready to use as a primary key or public-facing ID
• init(options) — a configurable factory that lets you set a custom id length (2-32 chars), a custom fingerprint, or a custom random function (e.g. a CSPRNG)
• isCuid(id, options) — a validator to check whether a string matches the expected cuid2 shape and length constraints
• A CLI (npx @paralleldrive/cuid2) for generating one or many ids or short slugs directly from the terminal, with an optional shell alias installer
• TypeScript type definitions (index.d.ts) shipped in the package, so consumers get full type safety with no extra @types install

Common Use Cases

• Generating primary keys for database rows created on the client before an insert, avoiding a round trip just to obtain an id
• Producing public-facing resource identifiers (e.g. in URLs) that don’t leak creation order or timing the way sequential or k-sortable ids do
• Creating short, human-shareable slugs (via a reduced length) for use cases like disambiguating usernames or short links
• Generating request/correlation ids in distributed systems where multiple hosts must produce non-colliding ids without a shared counter or lock

Under The Hood

Architecture

The library is a flat, single-module design centered on src/index.js, built as a small functional pipeline rather than a class hierarchy: createRandom picks between the Web Crypto API and Math.random as the entropy source, createEntropy and createFingerprint derive salt and host-identity strings, and init() closes over a counter, fingerprint, and random function to return a per-call id generator. The default createId export is a lazily-initialized singleton (via a small lazy(fn) wrapper) so fingerprint/counter setup is deferred until first use. The root index.js is a thin re-export layer over src/index.js, and bin/cuid2.js is a separate CLI entry point that imports the built index.js and translates argv flags into init() options. There is no deeper layering — changing the hash() function or the order entropy sources are concatenated in would change the shape of every id the library produces.

Tech Stack

The package is distributed as ESM only ("type": "module" with an exports map) and depends on @noble/hashes for an audited SHA3-512 implementation and bignumber.js to convert hash bytes into a big integer for base36 encoding. A separate error-causes dependency is used only in the maintainers’ own release.js script, not in the published library code. Build/release tooling includes ESLint 9 (flat config) with Prettier, a Husky pre-commit hook, and release-it for versioning. The repository also bundles a small Next.js app (next.config.js, pages/) used for a companion demo/visualization site (histogram and randogram pages), which is excluded from the published npm package via the files allowlist in package.json.

Code Quality

Tests live in src/index-test.js and src/bin-test.js, run directly with node using the riteway library’s given/should/actual/expected assertion style rather than a full test-runner framework. Beyond unit tests, the repo includes src/collision-test.js and src/histogram.js, which generate millions of ids across parallel processes and check the output distribution for statistical bias — a notably more rigorous validation approach than most id-generation libraries ship with. Hand-authored TypeScript definitions (index.d.ts) cover the public API and are checked against the test file via a dedicated tsc script. A GitHub Actions workflow (.github/workflows/ci.yml) runs checks on push, and ESLint/Prettier/Husky enforce style locally. Error handling is minimal but explicit — init() throws a descriptive Error when an invalid length is requested.

What Makes It Unique

Cuid2’s real innovation isn’t a new algorithm class but a deliberate entropy-composition strategy: it mixes a timestamp, a randomly-seeded session counter, a hashed host fingerprint, and CSPRNG output through a single NIST-standard hash function, and is intentionally tuned to not be maximally fast, since very fast id generation makes brute-force collision- and pattern-hunting attacks cheaper. That’s a different design goal than speed-optimized alternatives like nanoid or UUID v4, which don’t treat generation speed itself as an attack surface. It’s best understood as a thoughtful, security-focused evolution of the original Cuid rather than a groundbreaking new technique, but it fills a specific, well-articulated niche that most alternatives don’t target.