UUID v4 Generator

2.0.3 · active · verified Sun Apr 19

The `uuid4` package provides a lightweight and focused Node.js module specifically for generating and validating Version 4 UUIDs (Universally Unique Identifiers). As of its current stable version, 2.0.3, the library has shifted its compatibility focus to modern JavaScript environments, notably discontinuing support for legacy browsers that was available in its 1.x release line. This change means version 2.x and above are primarily designed for Node.js and modern browser environments that fully support ECMAScript Modules (ESM). While an explicit release cadence isn't detailed, the semantic versioning indicates a pattern of incremental updates and patch fixes. A key characteristic of `uuid4` is its simplicity for V4 generation. However, for users within the Deno ecosystem, the project itself recommends utilizing Deno's standard library UUID module for better native integration, highlighting a pragmatic approach to platform-specific best practices. The library offers a straightforward API for both creating new UUIDs and confirming the validity of existing ones against the RFC 4122 V4 specification.

Common errors

```
TypeError: uuid4_1 is not a function
```
cause Attempting to use `require('uuid4')` in a CommonJS file to import the default ESM export of `uuid4@2.x`.

fix Change your import statement to `import uuid4 from 'uuid4';` and ensure your environment supports ESM (e.g., `"type": "module"` in `package.json`).
```
SyntaxError: Cannot use import statement outside a module
```
cause You are using `import` statements (ESM syntax) in a JavaScript file that is being interpreted as a CommonJS module by Node.js or a bundler.

fix To enable ESM, add `"type": "module"` to your `package.json` or rename your file to use the `.mjs` extension. Alternatively, if you must use CommonJS, you may need to rely on `uuid4@1.x` or adjust your build pipeline.
```
ReferenceError: uuid4 is not defined (in browser console)
```
cause Trying to use `import uuid4 from 'uuid4';` directly in a browser without a module bundler or using the incorrect CDN path for the browser-specific module.

fix For direct browser usage without a build step, import the browser-specific ESM bundle: `import uuid4 from 'https://cdn.jsdelivr.net/gh/tracker1/node-uuid4/browser.mjs';`

Warnings

breaking Version 2.x of `uuid4` dropped support for legacy browsers. If your project requires compatibility with older browsers (e.g., Internet Explorer 11), you must remain on the 1.x release line.
Fix: For modern browser/Node.js environments, upgrade to `uuid4@2.x`. For legacy browser support, pin your dependency to `uuid4@1.x`.
gotcha The package's main entry point is ESM-only since version 2.x. Attempting to use `require()` for the default export will lead to runtime errors in Node.js environments unless specific CommonJS-ESM interop settings are configured.
Fix: Always use `import uuid4 from 'uuid4';` in your code. Ensure your Node.js project is configured for ESM (e.g., via `"type": "module"` in `package.json` or using `.mjs` file extensions).
gotcha For Deno projects, the `uuid4` package explicitly recommends using Deno's native `std/uuid` module instead of this package. The canonical Deno implementation offers better integration and stability within the Deno ecosystem.
Fix: In Deno, use `import { v4 as uuid4 } from 'https://deno.land/std/uuid/mod.ts';` for UUID generation and validation.

Install

npm install uuid4 npm
yarn add uuid4 yarn
pnpm add uuid4 pnpm

Imports

uuid4
wrong:
```
const uuid4 = require('uuid4');
```
correct:
```
import uuid4 from 'uuid4';
```
Since version 2.x, the package is ESM-only for its main entry point. CommonJS `require()` will not work directly for the default export.
valid
wrong:
```
import { valid } from 'uuid4';
```
correct:
```
import uuid4 from 'uuid4'; uuid4.valid(id);
```
The `valid` method for UUID validation is attached to the default `uuid4` export. While not explicitly shown as a named export in the README, it's typically accessed via the default import.
uuid4 (browser)
wrong:
```
import uuid4 from 'uuid4';
```
correct:
```
import uuid4 from 'https://cdn.jsdelivr.net/gh/tracker1/node-uuid4/browser.mjs';
```
For direct browser usage without a bundler, the specific browser-optimized ESM bundle must be imported via its full CDN path, not the bare package name.

Quickstart

Demonstrates how to generate a new V4 UUID and validate both generated and arbitrary UUID strings.

import uuid4 from "uuid4";

// Generate a new Version 4 UUID. These UUIDs are statistically unique
// and widely used for various identifiers where collision avoidance
// is crucial, such as unique database keys, session tokens, or transaction IDs.
const newId = uuid4();
console.log("Generated UUID:", newId); // Example: 'a1b2c3d4-e5f6-4789-0abc-1234567890ab'

// Validate a UUID to ensure it conforms to the V4 specification (RFC 4122).
// The validation is case-insensitive, making it robust for inputs from different sources.
// It checks for the correct format pattern (e.g., 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx').
const isValid = uuid4.valid(newId);
console.log("Is the generated UUID valid?", isValid); // Should always be true for newly generated IDs

// Example of validating an invalid UUID string.
const invalidId = "not-a-proper-uuid-format";
const isInvalidValid = uuid4.valid(invalidId);
console.log("Is 'not-a-proper-uuid-format' valid?", isInvalidValid); // Will be false

const anotherInvalid = "01234567-89ab-cdef-0123-456789abcdef"; // Not V4 (3rd block starts with 'c')
console.log("Is '" + anotherInvalid + "' valid?", uuid4.valid(anotherInvalid)); // Will be false (not V4 spec)

view raw JSON →