uuid — RFC-Compliant UUID Generation for JavaScript

Introduction

The uuid package is the canonical JavaScript implementation of RFC 9562 (formerly RFC 4122), providing functions to generate universally unique identifiers. It supports time-based, random, name-based, and the newer sortable UUID versions, making it the go-to choice for database keys, request tracing, and distributed system coordination.

What uuid Does

• Generates v1 (timestamp + MAC), v4 (random), v3/v5 (namespace + name hash) UUIDs
• Supports v6 (reordered timestamp) and v7 (Unix epoch millisecond sortable) from the latest RFC
• Validates UUID strings and extracts version/variant information
• Provides both ESM and CommonJS entry points with full TypeScript types
• Uses the Web Crypto API in browsers and crypto module in Node.js for secure randomness

Architecture Overview

Each UUID version has a dedicated generator function that assembles the 128-bit value according to RFC layout rules. The v4 generator fills 122 bits with crypto-random data and sets the version/variant nibbles. The v7 generator embeds a 48-bit Unix millisecond timestamp in the high bits for natural sortability, filling the remaining 74 bits with randomness. The library detects its runtime to select the most efficient random source.

Self-Hosting & Configuration

• Install via npm, yarn, or pnpm — zero dependencies
• Import individual version functions for tree-shaking: import { v4 } from 'uuid'
• Use uuid.validate(str) and uuid.version(str) for input validation in API endpoints
• For deterministic IDs, use v5 with a namespace UUID and a name string
• Works in Node.js 14+, all modern browsers, Deno, Bun, and Cloudflare Workers

Key Features

• Full RFC 9562 compliance including the latest v6 and v7 specifications
• Cryptographically secure random generation via native platform APIs
• Tree-shakeable ESM build — import only the versions you need
• TypeScript declarations included with branded UUID type
• Over 15,000 GitHub stars and 300 million weekly npm downloads

Comparison with Similar Tools

• nanoid — shorter URL-safe IDs; uuid produces standard 36-character RFC-compliant identifiers
• cuid2 — collision-resistant sortable IDs; uuid v7 offers similar sortability with RFC standardization
• ulid — 26-character sortable IDs; uuid v7 is the IETF-standardized sortable alternative
• crypto.randomUUID() — native v4 only; uuid supports v1, v3, v5, v6, v7 and validation utilities
• short-uuid — translates UUIDs to shorter encodings; uuid focuses on generation and validation

FAQ

Q: Which version should I use for database primary keys? A: Use v7 for new projects. Its time-sorted nature improves B-tree index locality in databases like PostgreSQL, MySQL, and MongoDB.

Q: Is v4 still recommended? A: Yes, for cases where sortability is not needed. It provides 122 bits of randomness and is the most widely deployed UUID version.

Q: How many v4 UUIDs before a collision? A: You would need to generate approximately 2.7 quintillion UUIDs to have a 50% probability of a single collision.

Q: Does it work in edge runtimes? A: Yes. The library uses globalThis.crypto when available, which covers Cloudflare Workers, Deno Deploy, and Vercel Edge.

Sources

• https://github.com/uuidjs/uuid
• https://www.rfc-editor.org/rfc/rfc9562