Generate UUID in Node.js

UUID v4 - Random (built-in, no deps)

import { randomUUID } from 'crypto';

// 122 bits of randomness - backed by libuv → OS CSPRNG
const id = randomUUID();
// → "550e8400-e29b-41d4-a716-446655440000"

UUID v7 - Time-ordered (requires uuid package)

// npm install uuid
import { v7 as uuidv7 } from 'uuid';

// Millisecond-precision timestamp prefix - sorts chronologically
const id = uuidv7();
// → "018e8f6a-1b2c-7d3e-9f4a-5b6c7d8e9f0a"

UUID v5 - Deterministic / Namespace-based

import { v5 as uuidv5 } from 'uuid';

// SHA-1 hash of namespace + name - same inputs always produce the same UUID
const id = uuidv5('example.com', uuidv5.DNS);
// → always "cfbff0d1-9375-5685-968c-48ce8b15ae17"

1. Express middleware - request tracing ID

import express from 'express';
import { randomUUID } from 'crypto';

const app = express();

// Inject a unique request ID into every request
app.use((req, res, next) => {
  req.id = randomUUID();
  res.setHeader('X-Request-ID', req.id);
  next();
});

app.get('/orders', (req, res) => {
  console.log(`[${req.id}] GET /orders`);
  res.json({ requestId: req.id });
});

2. Prisma - UUID primary key

// schema.prisma
// model User {
//   id    String @id @default(uuid())
//   name  String
// }

import { PrismaClient } from '@prisma/client';
import { randomUUID } from 'crypto';

const prisma = new PrismaClient();

// Prisma generates the UUID automatically via @default(uuid())
// Or supply your own for idempotent inserts:
async function createUser(name) {
  return prisma.user.create({
    data: { id: randomUUID(), name },
  });
}

3. Idempotency key for payment APIs

import { randomUUID } from 'crypto';

// Generate once, store, reuse on retry - prevents duplicate charges
async function chargeCustomer(customerId, amount) {
  const idempotencyKey = randomUUID();

  const response = await fetch('https://api.stripe.com/v1/charges', {
    method: 'POST',
    headers: {
      'Idempotency-Key': idempotencyKey,
      'Authorization': `Bearer ${process.env.STRIPE_KEY}`,
    },
    body: new URLSearchParams({ customer: customerId, amount }),
  });
  return response.json();
}

How do I generate a UUID in Node.js?

Node.js 19+ exposes a global crypto.randomUUID() that returns an RFC 4122 v4 UUID with zero dependencies. On Node 14.17 to 18, import it first with const { randomUUID } = require('node:crypto'). For v7, v5, or v3, install the uuid package.

Is crypto.randomUUID() cryptographically secure?

Yes. crypto.randomUUID() uses the platform CSPRNG (operating system secure random source), suitable for session tokens, API keys, and idempotency keys. Do not use non-cryptographic random sources for security-sensitive identifiers.

What is the difference between UUID v4 and v7 in Node.js?

UUID v4 (crypto.randomUUID() or equivalent) is fully random and not sortable. UUID v7 embeds a millisecond timestamp for chronological sorting (RFC 9562). Use v4 for general-purpose IDs; use v7 for database primary keys at scale.

Do I need to install a package for UUID generation in Node.js?

No additional package is required for basic v4 generation in Node.js. Check the Installation section for version-specific notes.

How do I validate a UUID string in Node.js?

Use the platform's UUID parse/validation function, or test against the RFC 4122 regex: /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i. Always validate external input at API boundaries.

Should I use UUIDs as database primary keys in Node.js applications?

UUIDs work well as primary keys for distributed systems. Prefer native UUID/BINARY(16) column types over VARCHAR(36). For very large tables, consider UUID v7 for better B-tree insert locality.

Can I generate UUIDs in Node.js without a network connection?

Yes. UUID generation uses local OS entropy sources and does not require network access. Each call is independent and thread-safe on modern platforms.

What output formats are available in Node.js?

The standard hyphenated lowercase string (36 chars) is the default. Most APIs also support 32-char hex (no hyphens) and 16-byte binary formats. Use string format for APIs and binary for database storage.

What RFC standards apply to Node.js UUID generation?

Version 4 UUIDs follow RFC 4122. UUID v7 follows RFC 9562 (May 2024). Ensure your chosen method produces compliant version and variant bits.

When should I avoid UUID v1?

Avoid UUID v1 in security-sensitive contexts - it embeds MAC address and timestamp information. Prefer v4 (crypto.randomUUID() or equivalent) unless you need legacy Cassandra timeuuid compatibility.