# uuid: RFC-Compliant UUID Generation for JavaScript, Node.js, and React Native

> The uuid npm package gives JavaScript developers a zero-dependency, tree-shakable library that covers all seven RFC9562 UUID versions. Starting with version 12, CommonJS is no longer supported, which requires an ESM-compatible build pipeline.

**uuidjs/uuid** — Generate RFC-compliant UUIDs in JavaScript

- Repository: https://github.com/uuidjs/uuid
- Stars: 15,334 · Forks: 984
- Language: TypeScript
- License: MIT
- Published: 2026-09-21 · Updated: 2026-09-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/uuidjs-uuid

## What uuid Solves and Who Needs It

Generating a Universally Unique Identifier in JavaScript historically meant writing a custom implementation or pulling in a dependency with a heavy tree. The uuid package removes both problems. It is a zero-dependency module, meaning nothing extra lands in your bundle, and it targets one narrowly defined job: producing RFC9562 (formerly RFC4122) UUIDs.

The README states four properties the package was built to deliver: complete coverage of all RFC9562 UUID versions; cross-platform support for TypeScript, Chrome, Safari, Firefox, Edge, Node.js, and React Native/Expo; security through the platform's modern crypto API for its random values; and a compact footprint that is tree-shakable so bundlers can drop every UUID version your code never calls.

The package suits web applications, backend services, and mobile apps that need a unique identifier for database records, session tokens, event tracking, or distributed coordination. It does not attempt to solve message queuing, distributed locking, or broader identity management. The package.json registers the package name as 'uuid' on npm, and the current release is v14.0.2 per the version field in that file.

## Installing and Generating a Version 4 UUID

Install the package with npm:

```bash
npm install uuid
```

The quickest path to a random UUID is the v4 function:

```javascript
import { v4 as uuidv4 } from 'uuid';

uuidv4(); // ⇨ 'b18794e8-5d0d-417c-b361-ba38e78411b4'
```

The README notes that starting with uuid version 12, CommonJS is no longer supported. Projects that still use require() must either stay on version 11 or migrate to ESM. The package's exports field in package.json shows a separate Node.js entry point at ./dist-node/index.js and a default entry at ./dist/index.js, each backed by TypeScript types at ./dist/index.d.ts.

## Timestamp-Based UUIDs: v1, v6, and v7

Random v4 UUIDs cannot be sorted by creation time. For cases where ordering matters, the package provides three timestamp-based variants.

Version 1 encodes a 60-bit timestamp derived from the system clock, a 14-bit clock sequence, and a 48-bit node field that defaults to a random value when none is supplied. The README warns that v1 throws an Error if more than 10 million UUIDs per second are requested. Version 6 reorders those timestamp bytes so UUIDs sort lexicographically by creation time. The library provides v1ToV6 and v6ToV1 conversion helpers so existing v1 identifiers can be migrated without regenerating them:

```javascript
import { v1ToV6 } from 'uuid';

v1ToV6('92f62d9e-22c4-11ef-97e9-325096b39f47'); // ⇨ '1ef22c49-2f62-6d9e-97e9-325096b39f47'
```

Version 7 places Unix Epoch milliseconds in the most significant bits, giving a natural sort order from the start. For new code that needs sortable identifiers, v7 is the more direct path than v1 plus a migration step. All three accept an optional options object to supply the timestamp, clock sequence, and node bytes manually, which is useful in tests or when generating a reproducible sequence.

## Deterministic Namespace UUIDs with v3 and v5

Versions 3 and v5 produce deterministic UUIDs: given the same name and namespace, the output is always identical. Version 3 uses MD5 hashing and version 5 uses SHA-1. The API shape is the same for both, taking a name string and a namespace UUID as arguments.

The README marks v8 as 'intentionally left blank': an API table entry exists but there is no working function because RFC9562 reserves version 8 for custom experimental formats. Code that imports uuid.v8 should not treat the export as an implementation.

NIL and MAX are two exported constants. NIL is the all-zeros UUID string ('00000000-0000-0000-0000-000000000000') and MAX is the all-ones UUID string ('ffffffff-ffff-ffff-ffff-ffffffffffff'). Both are useful as sentinel values in comparison logic.

## Parse, Stringify, Validate, and Inspect Utilities

Beyond generation, uuid provides four utility functions for working with UUID values.

The parse function converts a UUID string into a Uint8Array of 16 bytes, following the left-to-right hex-pair ordering of UUID strings:

```javascript
import { parse as uuidParse } from 'uuid';

uuidParse('6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b'); // ⇨
// Uint8Array(16) [
//   110, 192, 189, 127,  17,
//   192,  67, 218, 151,  94,
//    42, 138, 217, 235, 174,
//    11
// ]
```

The stringify function reverses that, accepting an array of 16 values between 0 and 255. A TypeError is thrown if the input to parse is not a valid UUID, or if stringify cannot produce a valid UUID string. The validate function returns a boolean for any input string without throwing. The version function returns the RFC version number of a valid UUID string, which is useful when handling identifiers generated by an external system.

## The Command-Line Interface and Browser Support

uuid registers a CLI in the package.json bin field at ./dist-node/bin/uuid. This lets you generate UUIDs from a shell without writing a script, which is useful for testing, seeding data in a Makefile, or one-off generation tasks.

For browser use, the README lists Chrome, Safari, Firefox, and Edge as supported. The library relies on the modern crypto API for random values, so any environment that provides a secure CSPRNG through the platform is covered. React Native and Expo are also listed. The sideEffects field in package.json is false, confirming that bundlers can safely tree-shake unused exports. The examples directory includes configurations for Webpack and Rollup to demonstrate bundling in a browser context. A browser-esmodules example and a browser-rollup example are both present alongside Node.js and TypeScript variants.

Native v4 UUID generation is available in modern browsers and recent Node.js releases through crypto.randomUUID(), but that built-in only covers v4. Projects that need v1, v5, v6, v7, the binary parse/stringify utilities, or validate/version detection still require a library like uuid.

## The CommonJS Break and What It Means for Upgrades

The most significant compatibility boundary in recent releases is the removal of CommonJS support starting with version 12. Teams on older toolchains that rely on require() cannot upgrade past uuid@11 without migrating to ESM first. The README links to an explainer on the motivation and the implications of the change. The package.json confirms the module type is 'module', reflecting this ESM-first stance.

The v8 function slot is present in the API table but is intentionally unimplemented. Version 1 imposes a hard limit of 10 million UUIDs per second before it throws an error, which matters for high-throughput batch jobs or code that calls v1 inside a tight loop.

The package does not offer built-in collision detection, deduplication, or persistence of generated UUIDs. It produces identifiers; the caller is responsible for managing uniqueness across a distributed system. Confirming that your target runtime exposes the Web Crypto API is the prerequisite step before adopting uuid, particularly for older browser targets or non-standard JavaScript environments where the crypto global may not be available.

## Conclusion

uuid suits any JavaScript or TypeScript project that needs RFC-compliant UUID generation across Node.js, browsers, or React Native, and its tree-shakable design means only the UUID versions you import end up in the bundle. Teams still on CommonJS must migrate to ESM before upgrading past version 11. The package.json confirms the current release is v14.0.2 and a CLI is registered at ./dist-node/bin/uuid for shell use.

## FAQ

### How do I generate a UUID in JavaScript?

Install the uuid package with npm install uuid, then import the v4 function using ESM syntax: import { v4 as uuidv4 } from 'uuid'. Calling uuidv4() returns a random RFC9562 UUID string.

### What is UUID in Node.js?

In the context of Node.js development, a UUID is a Universally Unique Identifier as defined in RFC9562. The uuid package provides a dedicated Node.js entry point at dist-node/index.js and supports all seven RFC versions on that runtime.

### How do I use the uuid package?

After npm install uuid, import the specific version function you need using ESM syntax, for example import { v4 as uuidv4 } from 'uuid', then call it to get an identifier. CommonJS require() is not supported from version 12 onward.

## Sources

- [Issues](https://github.com/uuidjs/uuid/issues)
- [License: MIT](https://github.com/uuidjs/uuid/blob/main/LICENSE)
- [README](https://github.com/uuidjs/uuid/blob/main/README.md)
- [Releases](https://github.com/uuidjs/uuid/releases)
- [uuidjs/uuid on GitHub](https://github.com/uuidjs/uuid)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/uuidjs-uuid