npmIntermediate

uuid

RFC9562 UUIDs

uuidunique-idguidrfc4122identityrfc9562typescript

The Problem

Generating unique identifiers that are truly unique across distributed systems, time, and machines without a centralised coordinator is a solved problem — but solving it correctly requires understanding RFC 4122 and avoiding common pitfalls like using Math.random() which has insufficient entropy.

Mental Model

UUID v4 generates a 128-bit random identifier with enough entropy that collisions are astronomically unlikely. UUID v1 encodes a timestamp and MAC address to guarantee uniqueness across time. The uuid library implements all RFC variants correctly and outputs them in the standard hyphenated string format.

60-second start

Install uuid

npm install uuid
import { } from 'uuid';

Use it when

Use uuid whenever you need a unique ID that doesn't require a database sequence: primary keys in distributed systems, idempotency keys for API calls, session tokens, file names, or correlation IDs for logging.

Skip it when

For database primary keys where you control the DB, auto-incrementing integers are smaller and faster to index. For sortable unique IDs (e.g. for pagination), consider ULID or UUIDv7, which encode a timestamp prefix.

Alternatives

nanoidGenerates shorter URL-safe IDs with comparable entropy — better when you need compact IDs in URLs

cuid2Collision-resistant, sortable, URL-safe IDs designed for databases — better than UUID for primary keys

crypto.randomUUIDBuilt into Node 14.17+ and modern browsers — no package needed for basic v4 UUIDs

Ready to explore the full API?

See every class, function, and relationship in an interactive graph.