nanoid の使い方完全ガイド — 軽量・安全なユニークID生成ライブラリ

一言でいうと

nanoid は、わずか118バイト（minified + brotli）の超軽量なユニークID生成ライブラリです。暗号学的に安全な乱数を使い、UUID より短い21文字のURL-safe な文字列IDを生成します。

どんな時に使う？

• データベースのプライマリキー生成 — UUIDの代わりに、より短くURLに安全なIDが欲しいとき
• ファイル名やURLスラッグの生成 — A-Za-z0-9_- のみで構成されるため、エンコード不要でURLにそのまま使える
• フロントエンドでの一時的なキー生成 — Reactのリストレンダリング用keyや、フォーム要素の一意な識別子として

インストール

# npm
npm install nanoid

# yarn
yarn add nanoid

# pnpm
pnpm add nanoid

注意: nanoid v5 は ESM (ES Modules) 専用です。CommonJS (require) では使用できません。CommonJS 環境が必要な場合は v3 系を使用してください。

基本的な使い方

import { nanoid } from 'nanoid'

// デフォルト: 21文字のユニークIDを生成
const id: string = nanoid()
console.log(id) //=> "V1StGXR8_Z5jdHi6B-myT"

// 長さを指定して生成
const shortId: string = nanoid(10)
console.log(shortId) //=> "IRFa-VaY2b"

生成されるIDは A-Za-z0-9_- の64文字（URL-safe）から構成されます。デフォルトの21文字で、UUIDと同等以上の衝突耐性（約126ビットのエントロピー）を持ちます。

よく使うAPI

1. nanoid(size?) — 基本のID生成

最も頻繁に使う関数です。暗号学的に安全な乱数（crypto.getRandomValues）を内部で使用します。

import { nanoid } from 'nanoid'

const id = nanoid()      // 21文字（デフォルト）
const id8 = nanoid(8)    // 8文字
const id36 = nanoid(36)  // 36文字

2. customAlphabet(alphabet, defaultSize?) — カスタム文字セットでID生成

使用する文字セットやデフォルトの長さをカスタマイズできます。

import { customAlphabet } from 'nanoid'

// 数字のみのID生成器を作成
const numericId = customAlphabet('0123456789', 12)
console.log(numericId()) //=> "839461827350"

// 小文字英字のみ
const lowercaseId = customAlphabet('abcdefghijklmnopqrstuvwxyz', 10)
console.log(lowercaseId()) //=> "qjmfbrtkxe"

// 呼び出し時に長さを上書きすることも可能
console.log(numericId(6)) //=> "294710"

3. urlAlphabet — デフォルトのアルファベット定数

nanoid が内部で使用している文字セットを参照できます。カスタムロジックを組む際に便利です。

import { urlAlphabet } from 'nanoid'

console.log(urlAlphabet)
//=> "useandom-26T198340PX75pxJACKVERYMINDBUSHWOLF_GQZbfghjklqvwyzrict"
// A-Za-z0-9_- の64文字（順序はランダム化されています）

4. nanoid (非セキュア版) — 高速だがセキュリティ不要な場面向け

パフォーマンスが最優先で、暗号学的安全性が不要な場合に使います。

import { nanoid } from 'nanoid/non-secure'

const id = nanoid()
console.log(id) //=> "Uakgb_J5m9g-0JDMbcJqLJ"

⚠️ 注意: nanoid/non-secure は Math.random() を使用するため、セキュリティが求められる場面（認証トークン等）では絶対に使わないでください。

5. customRandom(alphabet, size, random) — 乱数ソースの完全カスタマイズ

乱数生成関数自体を差し替えたい場合に使います。テスト時のシード固定などに有用です。

import { customRandom } from 'nanoid'

// カスタム乱数ソースを使ったID生成器
const myRandom = customRandom(
  'abcdef',
  10,
  (size) => {
    return new Uint8Array(size).fill(1) // テスト用の固定値
  }
)

console.log(myRandom()) //=> 常に同じ値を返す（テスト用途）

類似パッケージとの比較

選定の目安:

• とにかく軽量・シンプル → nanoid
• RFC 4122 準拠が必要 → uuid
• 時系列ソートが必要 → ulid
• 分散環境での衝突耐性を重視 → cuid2

注意点・Tips

ESM 専用であることに注意（v5）

nanoid v5 は Pure ESM パッケージです。require('nanoid') は動作しません。

// package.json で "type": "module" を指定するか、
// .mjs 拡張子を使用してください
{
  "type": "module"
}

Next.js や Vite など、ESM をネイティブサポートするフレームワークでは問題なく動作します。

ID長と衝突確率の関係

nanoid の公式衝突計算ツールで確認できます。目安として：

短いIDを使う場合は、用途に応じて衝突リスクを必ず検討してください。

React での使い方

React 18 以降では useId() が組み込まれていますが、これはサーバー/クライアント間のハイドレーション整合性のためのものです。データベースIDやビジネスロジック用のIDには nanoid を使いましょう。

import { nanoid } from 'nanoid'

interface Todo {
  id: string
  text: string
}

const addTodo = (text: string): Todo => ({
  id: nanoid(),
  text,
})

TypeScript の型

nanoid は TypeScript の型定義を同梱しているため、@types/nanoid のインストールは不要です。

まとめ

nanoid は「小さく、安全で、短い」という三拍子揃ったID生成ライブラリです。118バイトという驚異的な軽量さでありながら、暗号学的に安全な乱数を使用し、UUIDより短い21文字でほぼ同等の衝突耐性を実現します。カスタムアルファベットによる柔軟なID形式の定義も可能で、多くのプロジェクトにおいてUUIDの優れた代替となるでしょう。