Tiny and Fast Unique ID Generator

2.0.2 · active · verified Sun Apr 19

The `uid` package provides a highly optimized and compact utility for generating fixed-length random unique IDs in JavaScript environments, supporting both Node.js and browsers. The current stable version is 2.0.2, with releases focusing on performance, bug fixes, and TypeScript compatibility, indicating an active maintenance and development cadence. Key differentiators include its extremely small footprint (130B to 205B gzipped) and high performance, with benchmarks showing it to be significantly faster than alternatives like `nanoid` in its default non-secure mode. It offers three distinct modes: `uid` (fast, `Math.random`-based, non-secure), `uid/secure` (cryptographically secure via `crypto.getRandomValues`), and `uid/single` (non-secure, no internal cache, ideal for short-lived environments). This flexibility allows developers to choose the appropriate balance of speed, security, and bundle size for their specific use case.

Common errors

```
TypeError: Cannot read properties of undefined (reading 'length')
```
cause Attempting to call `uid()` directly after an incorrect `import uid from 'uid';` statement in v2.0.0+ ESM environments, where `uid` is `undefined` because it's no longer the default export.

fix Change the import statement to `import { uid } from 'uid';`.
```
TypeError: uid is not a function
```
cause In CommonJS environments, attempting to call `require('uid')()` directly after the v2.0.0 breaking change. `require('uid')` now returns an object `{ uid: Function }`, not the function itself.

fix Destructure the `uid` function: `const { uid } = require('uid');`.

Warnings

breaking The `uid` package changed its default export to a named export in v2.0.0. Code relying on `import uid from 'uid';` will break.
Fix: Change `import uid from 'uid';` to `import { uid } from 'uid';`. For CommonJS, `const uid = require('uid');` should become `const { uid } = require('uid');`.
gotcha The default `uid` export and `uid/single` mode rely on `Math.random` and are NOT cryptographically secure. They should not be used for security-sensitive applications where unpredictability is paramount.
Fix: For cryptographically secure unique IDs, use `import { uid } from 'uid/secure';`. Ensure the environment (Node.js or browser) supports the Web Crypto API's `crypto.getRandomValues()`.
gotcha The `uid/secure` mode requires the environment's `crypto` module (specifically `crypto.getRandomValues`). In older or constrained environments without this API, `uid/secure` will not function correctly.
Fix: Verify `crypto.getRandomValues` availability in target environments if using `uid/secure`. For universal compatibility or non-security-critical needs, fall back to the default `uid` or `uid/single`.
gotcha While `uid` aims for uniqueness, the risk of collisions increases with shorter lengths and a higher number of generated IDs. The default length of 11 uses a hexadecimal alphabet.
Fix: For applications requiring a very high guarantee of uniqueness, consider using longer ID lengths or cryptographically secure methods (`uid/secure`) and evaluate the probability of collisions based on your specific use case.

Install

npm install uid npm
yarn add uid yarn
pnpm add uid pnpm

Imports

uid
wrong:
```
import uid from 'uid';
```
correct:
```
import { uid } from 'uid';
```
Since v2.0.0, the default export was replaced with a named export `uid` for the non-secure `Math.random` based ID generation.
uid (secure)
wrong:
```
import uidSecure from 'uid/secure';
```
correct:
```
import { uid } from 'uid/secure';
```
The secure, cryptographically random ID generator is imported from a subpath. It also uses a named export `uid`.
uid (single)
wrong:
```
const { uid } = require('uid/single');
```
correct:
```
import { uid } from 'uid/single';
```
The 'single' mode, ideal for short-lived environments without an internal cache, is imported via a subpath and uses a named `uid` export. ES module imports are preferred.
CommonJS require (secure)
wrong:
```
const uidSecure = require('uid/secure').default;
```
correct:
```
const { uid } = require('uid/secure');
```
For CommonJS environments, ensure you destructure the named `uid` export from the subpath.

Quickstart

Demonstrates how to import and use the default, secure, and single-use `uid` generators with custom lengths.

import { uid } from 'uid';
import { uid as secureUid } from 'uid/secure';
import { uid as singleUid } from 'uid/single';

// Generate a default non-secure ID (length 11, hexadecimal alphabet)
const id1 = uid();
console.log(`Default non-secure ID: ${id1}`); // e.g., 'c92054d1dd6'

// Generate a non-secure ID with custom length
const id2 = uid(16);
console.log(`Non-secure ID (length 16): ${id2}`); // e.g., '8234dbf9a7dcec3b'

// Generate a cryptographically secure ID (length 11, hexadecimal alphabet)
// Requires crypto.getRandomValues() support (Node.js & modern browsers)
const secureId = secureUid();
console.log(`Secure ID: ${secureId}`); // e.g., 'f8a4b6c1e9d0a2b'

// Generate a single-use ID (length 11, alphanumeric alphabet)
// Does not maintain an internal buffer, good for ephemeral contexts
const singleUseId = singleUid();
console.log(`Single-use ID: ${singleUseId}`); // e.g., 'aG5jK7lP2qR'

// Example of generating multiple IDs within a loop
for (let i = 0; i < 3; i++) {
  console.log(`Loop ID ${i}: ${uid(8)}`);
}

view raw JSON →