uuid の使い方 — JavaScriptでUUIDを生成するデファクトスタンダード

一言でいうと

uuid は、RFC9562（旧RFC4122）に準拠したUUIDを生成するためのJavaScriptライブラリです。v1〜v7まですべてのバージョンに対応し、Node.js・ブラウザ・React Nativeで動作します。

どんな時に使う？

• データベースのプライマリキー生成 — ユーザーやリソースに一意なIDを振りたいとき（v4やv7が定番）
• 分散システムでの一意識別子 — 複数サーバー間で衝突しないIDが必要なとき
• 名前空間ベースの決定的ID生成 — 同じ入力から常に同じUUIDを得たいとき（v5を使用）

インストール

# npm
npm install uuid

# yarn
yarn add uuid

# pnpm
pnpm add uuid

TypeScriptの型定義は本体に同梱されているため、@types/uuid は不要です。

⚠️ 注意: uuid@12 以降、CommonJS（require()）はサポートされていません。ESModules（import）を使用してください。

基本的な使い方

最も一般的なユースケースは、ランダムなUUID v4の生成です。

import { v4 as uuidv4 } from 'uuid';

const id: string = uuidv4();
console.log(id); // => '9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d'

時刻ベースでソート可能なUUIDが必要な場合は、v7が推奨されます。

import { v7 as uuidv7 } from 'uuid';

const id: string = uuidv7();
console.log(id); // => '01932c08-7e3b-7cc4-9014-842813c8221f'

よく使うAPIと使い方

1. v4() — ランダムUUIDの生成

最も広く使われるバージョンです。暗号学的に安全な乱数（crypto API）を使用します。

import { v4 as uuidv4 } from 'uuid';

// 基本的な使い方
const id = uuidv4(); // => 'f47ac10b-58cc-4372-a567-0e02b2c3d479'

// バイト配列に直接書き込む
const buffer = new Uint8Array(16);
uuidv4(undefined, buffer, 0);
console.log(buffer); // => Uint8Array(16) [...]

2. v7() — Unix Epochタイムスタンプ付きUUID

タイムスタンプを含むため、生成順にソート可能です。データベースのプライマリキーに最適です。

import { v7 as uuidv7 } from 'uuid';

const id1 = uuidv7();
const id2 = uuidv7();

// id1 < id2 が時系列順で保証される
console.log(id1 < id2); // => true

3. v5() — 名前空間ベースのUUID（SHA-1）

同じ名前空間と名前から、常に同じUUIDを生成します。冪等なID生成に便利です。

import { v5 as uuidv5 } from 'uuid';

// 定義済み名前空間を使用
const MY_NAMESPACE = '1b671a64-40d5-491e-99b0-da01ff1f3341';

const id1 = uuidv5('hello', MY_NAMESPACE);
const id2 = uuidv5('hello', MY_NAMESPACE);

console.log(id1 === id2); // => true（同じ入力なら同じ結果）

// RFC定義済みの名前空間も利用可能
import { v5, NIL } from 'uuid';
const urlId = v5('https://example.com', v5.URL);
const dnsId = v5('example.com', v5.DNS);

4. validate() / version() — UUIDの検証とバージョン判定

import { validate, version } from 'uuid';

// 有効なUUIDかどうかを判定
validate('9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d'); // => true
validate('not-a-uuid'); // => false

// UUIDのバージョンを取得
version('9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d'); // => 4

5. parse() / stringify() — 文字列とバイト配列の相互変換

バイナリプロトコルやデータベースのバイナリ型カラムとの連携に使います。

import { parse, stringify } from 'uuid';

// 文字列 → バイト配列
const bytes: Uint8Array = parse('6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b');
console.log(bytes); // => Uint8Array(16) [110, 192, 189, ...]

// バイト配列 → 文字列
const str: string = stringify(bytes);
console.log(str); // => '6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b'

補足: 定数 NIL / MAX

import { NIL, MAX } from 'uuid';

console.log(NIL); // => '00000000-0000-0000-0000-000000000000'
console.log(MAX); // => 'ffffffff-ffff-ffff-ffff-ffffffffffff'

類似パッケージとの比較

選び方の目安:

• RFC準拠が必要 → uuid
• とにかく短いIDが欲しい → nanoid
• ソート可能 + 短いID → ulid
• v4だけで十分 & 依存を増やしたくない → crypto.randomUUID()

注意点・Tips

CommonJSは非サポート（v12以降）

// ❌ これは動かない
const { v4 } = require('uuid');

// ✅ ESModulesを使う
import { v4 } from 'uuid';

package.json に "type": "module" を設定するか、.mts ファイルを使用してください。

v4 vs v7 の使い分け

• v4: 完全にランダム。IDから時刻情報を漏らしたくない場合に適切
• v7: タイムスタンプ内蔵でソート可能。RDBのB-Treeインデックスと相性が良く、INSERT性能が向上する場合がある。新規プロジェクトではv7が推奨される傾向

v1のnode IDはプロセス起動時に固定される

v1() が使うnode ID（UUIDの末尾12桁）は、プロセス起動時にランダム生成され、以降変わりません。意図的に変更したい場合は options.node を指定してください。

Tree-shakingを活かす

名前付きインポートを使えば、使用しないバージョンのコードはバンドルに含まれません。

// ✅ v4のコードだけがバンドルされる
import { v4 } from 'uuid';

// ❌ 全APIがバンドルされる可能性がある
import * as uuid from 'uuid';

CLIとしても使える

npx uuid v4
# => 1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed

npx uuid v7
# => 01932c08-7e3b-7cc4-9014-842813c8221f

ちょっとしたテストデータの生成やシェルスクリプトでの利用に便利です。

まとめ

uuid はRFC9562に完全準拠したUUID生成ライブラリで、v1〜v7のすべてのバージョンをサポートしています。新規プロジェクトでは、ランダムIDなら v4()、ソート可能なタイムスタンプ付きIDなら v7() を選ぶのが現在のベストプラクティスです。ゼロ依存・Tree-shaking対応で、バンドルサイズへの影響も最小限に抑えられます。