uuid is generated documentation in an ESM-only, two-build package
Generate RFC-compliant UUIDs in JavaScript
At a glance
- What is it?
- uuid creates RFC9562 UUIDs, previously RFC4122, in TypeScript with zero dependencies and a tree-shakable build. Three details shape how you consume it. The README is auto-generated, so edits to it are lost. CommonJS support ended at uuid@12 and the current major is 14. And the package publishes a different build to Node than to bundlers, through conditional exports.
- Who is it for?
- uuid is a good default when you want RFC9562 compliance with no runtime dependencies and a build that tree-shakes, and the version 7 generator is the sensible choice for anything database-backed. Three things to check first.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 14 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- uuidjs/uuid15,346 ★ · +16
| Repository | 2026-09-21 | 2026-11-15 |
|---|---|---|
| uuidjs/uuid | 15.3k | 15.3k |
16 Stars in the last 55 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
The README is generated, so edits to it do not survive
The first thing in the README file is a comment, and it is about the README itself:
This file is auto-generated from README_js.md. Changes should be made there.
The repository root confirms the arrangement, holding both README.md and README_js.md, and the package scripts include a docs check that regenerates the documentation and then runs git diff against README.md.
So there is a documented workflow for catching an out-of-date README: regenerate it and let the diff tell you whether it is stale. That is a sensible arrangement, and it also means the front page you are reading is a build artefact.
The consequence for anyone who wants to correct something, clarify a line or add an example is that editing README.md directly will not persist. The next documentation run overwrites it, and in a pull request the difference shows up as a conflict or as a silent revert.
Make the change in README_js.md. If you are forking this project and want to adjust the documentation, that one comment at the top of the file is the whole instruction.
CommonJS ended at version 12, and the package is now at 14
There is a note near the top of the README, and it is the kind of breaking change that people discover at upgrade time rather than at read time.
Starting with uuid version 12, CommonJS is no longer supported. Links are given to a write-up of the implications and to an issue explaining the motivation.
Set against the current state, the manifest declares version 14.0.3 with type set to module, and the recent release list shows 14.0.3, 14.0.2 and 14.0.1. So the CommonJS era ended two majors ago and the package has moved on again since.
In a codebase still on CommonJS, this is a hard stop that needs a migration of the consuming code or of the build tooling around it, and it is not something you find by reading the changelog of the patch you happened to upgrade to.
So check the module system of the consuming project before the version bump rather than after. The migration is entirely on your side, since the library made the decision.
Version 8 is struck through and left deliberately blank
The API summary table lists every generator, and one row is formatted differently from all the others.
The entry for uuid.v8() is struck through, and its description reads: Intentionally left blank.
That is not a missing feature awaiting a pull request. It is a deliberate statement that this library will not produce version 8 UUIDs, in an API that otherwise claims complete support for all RFC9562 versions.
The reasoning behind it is worth understanding. The specification reserves the version nibble for custom, experimental use, so a library producing version 8 values would be minting identifiers whose meaning is defined by whoever wrote the code, not by the standard. Writing your own such values and expecting other systems to interpret them is the trap.
So if you arrive from a codebase that has a v8 helper of its own, this library will not replace it, and the README is telling you so rather than leaving you to discover it. Handle those values yourself.
Node and bundlers resolve to different built files
The exports map in the package manifest is conditional, and the condition is the runtime rather than the format.
The main entry point has a node condition and a default condition. Under node it resolves types and then a default pointing at one build directory; under default it resolves to a different file in another build directory. A package.json subpath is also exported separately.
So there are two builds in the package. The files array confirms it, listing two output directories plus a negation for tests, and the bin entry points at a file inside the node-specific one.
Two things follow. The code your bundler analyses and the code that runs under Node are different artefacts, so a bug or a size difference in one is not evidence about the other. And the browser and bundler path is the one marked tree-shakable, reinforced by sideEffects set to false and a bundlewatch configuration in the repository to police the size.
The practical consequence is that a size regression or an environment-specific bug has to be reproduced in both paths before you conclude which one your users are hitting.
Version 1 uses a random node field and throws above ten million per second
Two properties of the version 1 generator are easy to assume and worth reading.
The quickstart is the whole getting started path. Install with:
npm install uuidThen import the generator you want and call it:
import { v4 as uuidv4 } from 'uuid';
uuidv4(); // ⇨ 'b18794e8-5d0d-417c-b361-ba38e78411b4'Now the version 1 specifics. In the options table, options.node defaults to random, described as the RFC node field as an array of six byte values. There is also a random clock sequence and a random byte source by default.
So version 1 here does not derive its node from a network interface. It is a random value chosen at generation time, alongside a random clock sequence and a timestamp taken from the current time, with an optional nanosecond field defaulting to zero. Anyone assuming that a version 1 UUID encodes a stable hardware identity, or that it is stable across restarts, is reading a different implementation.
Installing the library puts a uuid binary on your PATH
The package declares a bin entry, mapping the name uuid to a file inside the node build, and the README advertises a command line utility as one of its five headline features alongside completeness, cross-platform support, security and compactness.
That means a plain dependency install of this library places an executable named uuid in your local bin directory, or in a global location depending on how you installed.
It is a minor surprise that costs a moment of confusion the first time it happens, particularly on a machine that already has something else called uuid on the PATH, or in a container image where an unexpected executable appears in the build step.
Because the bin entry is part of the package, the CLI is present in every install of the library rather than only when you ask for it.
Four formatting and linting tools share one repository
The development toolchain is broad for a library whose runtime footprint is nothing, and the overlap is worth noting.
There is a biome configuration file and biome in the dependencies. There is a prettier configuration file and prettier in the dependencies. There is a neostandard configuration in the dependencies, which is a shareable eslint configuration. And there is lint-staged together with a lefthook configuration file for running checks on commit.
Four overlapping tools for one job is not automatically wrong. Biome can own linting and formatting, prettier can be kept for compatibility with existing editor setups, neostandard provides the rules that biome does not, and lint-staged with lefthook wires them to git hooks. But a contributor adding a file has to work out which of them is authoritative; CONTRIBUTING.md is the place to look.
The cross-platform support claim is where this shows up as real cost. Alongside the browser and Node examples for ES modules, rollup, webpack and jest, there is a TypeScript example, a bundlewatch configuration to enforce size budgets, and optional WebdriverIO dependencies including a BrowserStack service, which is how the browser claims get tested rather than asserted.
Editorial conclusion
uuid is a good default when you want RFC9562 compliance with no runtime dependencies and a build that tree-shakes, and the version 7 generator is the sensible choice for anything database-backed. Three things to check first. Confirm your project is ESM, because the CommonJS path was removed two majors ago. Confirm the version 1 default will not surprise you, since its node field is random rather than a hardware address. And if you rely on documentation, edit the source file the README is generated from, not the README.
Frequently asked questions
How to generate a UUID in JS?
Install the package with npm install uuid, then import the version 4 generator and call it. The quickstart shows importing v4 as uuidv4 and calling it, which returns a string such as b18794e8-5d0d-417c-b361-ba38e78411b4. Timestamp, namespace and other generators are imported the same way.
What is UUID in nodejs?
It is the package uuid, which publishes separate builds for Node and for bundlers through conditional exports, with the Node condition resolving to its own output directory. Its manifest declares type as module, so CommonJS require is not supported, a change that took effect at version 12.
How do I use UUID?
Install with npm install uuid and import the generator you need: version 4 for random, version 7 for Unix epoch time-based, version 1 for timestamp, and versions 3 and 5 for namespace-based generation with MD5 and SHA-1. There are also helpers to parse a UUID string into a byte array and stringify one back, plus validate and version detection.
What does UUID stand for?
The project describes itself as being for the creation of RFC9562 UUIDs, noting that this specification was formerly RFC4122, and claims complete support for all RFC9562 versions. The list of available versions covers 1, 3, 4, 5, 6 and 7, with version 8 marked as intentionally left blank.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/uuidjs-uuid)Star history chart for your README
[](https://hysenlabs.com/projects/uuidjs-uuid)Was this useful?