nanoid

A tiny, secure, URL-friendly unique string ID generator for JavaScript and TypeScript

Library
npm
v6.0.2
27,123 stars
MIT License

Repository Health

Pre-computed score based on development activity, maintenance, community, maturity, and trend momentum. How we score it →
80 /100 Excellent
Development Activity 84
Maintenance 72
Community 64
Maturity 60
Momentum 40

Technical Analysis

AI-assessed by reading the actual repository — architecture, code quality, innovation, and documentation. How we score it →
90 /100 Excellent
Architecture 90
Code Quality 92
Innovation 90
Learning Curve 90

Nanoid is a tiny, secure, URL-friendly unique string ID generator for JavaScript. At just 118 bytes minified and gzipped, it has no runtime dependencies and generates IDs that are shorter than a UUID (21 characters by default) while offering a comparable collision probability, thanks to a larger URL-safe alphabet and hardware-backed randomness.

Beyond the default generator, Nanoid exposes customAlphabet and customRandom for teams that need a specific character set, ID length, or an alternate random source, plus a non-secure variant for environments without a hardware random generator. It ships with first-class TypeScript types, a small CLI for generating IDs from the terminal, and ports in over twenty other programming languages so the same ID scheme can be shared across a full stack.

What You Get

  • A zero-dependency nanoid() function that returns a 21-character URL-safe ID with collision odds comparable to UUID v4
  • customAlphabet() and customRandom() for generating IDs with a custom character set, length, or random source
  • A non-secure build for environments (like offline demos) that don’t need cryptographic randomness
  • First-class TypeScript declarations, including support for opaque branded ID types
  • A standalone npx nanoid CLI for generating IDs from the command line
  • Ports of the same ID algorithm in 20+ other languages for cross-stack ID consistency

Common Use Cases

  • Generating primary keys or record IDs in databases without relying on auto-increment or full UUIDs
  • Creating short, URL-safe identifiers for shareable links, slugs, or public resource IDs
  • Assigning client-side unique keys for React/Vue lists or optimistic UI updates
  • Producing session, request, or trace IDs for logging and distributed tracing

Under The Hood

Architecture — The package is deliberately small and single-purpose: index.js defines random(), customRandom(), and customAlphabet(), and composes the default nanoid export as customAlphabet(urlAlphabet); url-alphabet/index.js holds the compression-optimized default alphabet as a standalone module so it can be tree-shaken independently; non-secure/index.js re-implements the same API on top of Math.random() for non-cryptographic use; and bin/nanoid.js is a thin CLI wrapper that parses --size/--alphabet flags and calls straight into the library functions, keeping the CLI and library behavior identical.

Tech Stack — Nanoid has zero runtime dependencies and ships as native ESM ("type": "module") with a browser-specific entry (index.browser.js) mapped via the browser and react-native package.json fields, plus hand-written index.d.ts TypeScript declarations rather than a build step. Development tooling is modern and minimal: oxlint/oxfmt for linting and formatting, vite for the interactive demo, size-limit to enforce the documented byte budgets (118 B for nanoid, 207 B for customAlphabet), and tinybench/better-node-test (bnt) for benchmarking and testing, orchestrated through a pnpm workspace.

Code Quality — The test suite (test/index.test.js, test/non-secure.test.js, test/pool.test.js, test/bin.test.js, ~556 lines total) is run with bnt --coverage 100, enforcing full statement coverage on every change, and a simple-git-hooks pre-commit hook runs check-versions.js to keep versions consistent across package.json, jsr.json, and docs. The randomness code in index.js is unusually heavily commented, explaining the modulo-bias rejection sampling, the power-of-two fast path, and the string-pool optimization ported from the nope-id project, which makes an otherwise dense, performance-critical file easy to audit. Invalid input (negative size) throws an explicit RangeError rather than failing silently.

API Design — The public surface is intentionally tiny: nanoid() needs no arguments and no configuration to produce a safe ID, while customAlphabet() and customRandom() share a consistent (alphabet, defaultSize, [random]) shape for advanced cases, and TypeScript generics let consumers cast the result into an opaque ID type. The CLI mirrors the library’s flags one-to-one, and the README documents framework-specific guidance (React key warnings, React Native polyfills, PouchDB/CouchDB ID prefixing) that heads off common misuse before it happens.

Join founders buildingwith open source

Opinionated takes, migration guides, cost-saving tips, and insights from the open source ecosystem.

Subscribe on Substack
Join 750+ subscribers