The Complete Guide to CUID
Everything you need to know about Collision-resistant Unique Identifiers, from basic concepts to advanced implementation patterns.
01 What is CUID?
CUID stands for Collision-resistant Unique IDentifier. It's a type of identifier specifically designed to be unique across distributed systems without requiring coordination between different machines or processes.
Anatomy of a CUID
cjld2cjxh0000qzrmn831i7rnUnlike auto-incrementing database IDs that require a central authority, or UUIDs that are cumbersome to read and type, CUIDs offer a practical middle ground: they're short enough to be human-readable, URL-safe, and can be generated independently on any device.
02 History and Evolution
CUID was created by Eric Elliott, a well-known JavaScript developer and author. The project was born out of practical needs at a startup where traditional ID generation methods were causing problems in a distributed architecture.
Original CUID released as an open-source project. Gained popularity in the Node.js community as a lighter, web-safe UUID alternative.
CUID2 released with improved security, using cryptographically secure random generation and removing predictable timestamp encoding.
03 How CUID Works
A CUID v1 is composed of several components, each serving a specific purpose in ensuring uniqueness. This structure was designed to be horizontally scalable:
| Component | Length | Purpose |
|---|---|---|
| c | 1 char | Constant prefix identifying it as a CUID |
| timestamp | 8 chars | Base36 encoded milliseconds since epoch |
| counter | 4 chars | Incrementing counter for same-ms generation |
| fingerprint | 4 chars | Machine/process identifier |
| random | 8 chars | Random characters for additional entropy |
04 CUID vs CUID2
CUID2 represents a significant shift in philosophy. While CUID v1 relied on machine fingerprinting and timestamps, CUID2 relies on strong entropy and cryptography.
| Feature | CUID v1 | CUID2 |
|---|---|---|
| Default Length | 25 characters | 24 characters |
| Timestamp Encoded | Yes (extractable) | No (hidden for security) |
| Generation | Math.random() | Cryptographically secure |
| Configurable Length | No | Yes (2-32 chars) |
Our Recommendation
Use CUID2 for all new projects, especially for security-sensitive applications. Use CUID v1 only if you have a specific requirement for extracting timestamps or simple time-based sorting.
05 Use Cases
🗄️ Primary Keys
Ideal for distributed databases. Generate IDs client-side before saving, optimizing performance and enabling offline-first apps.
🔗 URL Slugs
URL-safe by default (no special chars). Shorter and prettier than UUIDs. Perfect for share links and public profiles.
📁 File Naming
Safe for all filesystems. Avoids collision issues when uploading user-generated content to cloud storage.
🔐 Tokens (CUID2)
CUID2's cryptographic security makes it suitable for non-critical session tokens and API keys.
06 When Not to Use
While CUIDs are versatile, they aren't a silver bullet. Consider alternatives if:
- ✗Strict Storage LimitsCUIDs take ~25 bytes (string). Integers take 4-8 bytes.
- ✗Strict Sequential RequirementsIf you need gap-less sequences like Invoice Numbers (INV-001, INV-002), use auto-increment.
- ✗Legacy UUID ComplianceSome enterprise systems STRICTLY require 36-char RFC 4122 strings.
07 Getting Started
Ready to integrate CUID?
Check out our comprehensive code examples to get started in your preferred language in seconds.