Generate UUID in TypeScript

Step-by-Step Guide

Follow these four steps to generate, type, and safely validate UUIDs in any TypeScript project.

1. 1

   Configure your TypeScript environment

   Browser projects need "DOM" and "ES2021" (or later) in compilerOptions.lib. Node projects need @types/node. Without the correct lib, crypto.randomUUID() may be untyped or missing.

   tsconfig.jsonCopy

   {
     "compilerOptions": {
       "target": "ES2022",
       "lib": ["ES2022", "DOM"],
       "module": "ESNext",
       "moduleResolution": "bundler",
       "strict": true
     }
   }

2. 2

   Generate a typed UUID v4

   Call crypto.randomUUID() and cast to your branded UUID type. In Node.js 14.17–18, import from node:crypto instead.

   typescriptCopy

   type UUID = string & { readonly _brand: 'UUID' };
   
   // Browser / Node 19+
   const id: UUID = crypto.randomUUID() as UUID;
   
   // Node 14.17–18
   import { randomUUID } from 'node:crypto';
   const serverId: UUID = randomUUID() as UUID;

3. 3

   Create entity-specific branded types

   Define UserId, OrderId, and other domain IDs as distinct branded types. TypeScript will catch passing the wrong ID at compile time.

   typescriptCopy

   type UserId  = UUID & { readonly _brand: 'UserId' };
   type OrderId = UUID & { readonly _brand: 'OrderId' };
   
   function createUserId(): UserId  { return crypto.randomUUID() as UserId; }
   function createOrderId(): OrderId { return crypto.randomUUID() as OrderId; }
   
   function getOrder(id: OrderId): Promise<Order> { /* ... */ }
   
   const userId  = createUserId();
   const orderId = createOrderId();
   getOrder(orderId); // ✓ OK
   // getOrder(userId); // ✗ compile-time error

4. 4

   Validate external UUIDs at runtime

   Types are erased at runtime. Always validate UUIDs from HTTP requests, query params, and user input with a type guard or Zod schema.

   typescriptCopy

   import { z } from 'zod';
   
   // Zod 3
   const UUIDSchema = z.string().uuid();
   // Zod 4: const UUIDSchema = z.uuid();
   
   function parseUserId(input: unknown): UserId {
     const id = UUIDSchema.parse(input);
     return id as UserId;
   }

Quick Reference

Choose the right approach for generation, typing, and validation.

Environment Compatibility

crypto.randomUUID() availability and TypeScript typing across runtimes.

All UUID Versions

// Return type: `${string}-${string}-${string}-${string}-${string}`
const id = crypto.randomUUID();
// → "550e8400-e29b-41d4-a716-446655440000"

import { v7 as uuidv7 } from 'uuid';

const id: string = uuidv7();
// → "018e8f6a-1b2c-7d3e-9f4a-5b6c7d8e9f0a"
// Later IDs sort after earlier ones (RFC 9562)

import { v5 as uuidv5 } from 'uuid';

const id = uuidv5('example.com', uuidv5.DNS);
// → always "cfbff0d1-9375-5685-968c-48ce8b15ae17"

import { v1 as uuidv1, v3 as uuidv3, v6 as uuidv6 } from 'uuid';

uuidv1(); // timestamp + MAC-based node
uuidv3('hello', uuidv3.URL); // MD5 namespace hash
uuidv6(); // reordered v1 for better DB locality (RFC 9562)

Validate and Parse UUIDs

TypeScript types do not validate runtime input. Always check UUIDs from HTTP requests, query params, and external APIs.

type UUID = string & { readonly _brand: 'UUID' };

const UUID_RE =
  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;

function isUUID(value: unknown): value is UUID {
  return typeof value === 'string' && UUID_RE.test(value);
}

function toUUID(value: unknown): UUID {
  if (!isUUID(value)) throw new TypeError('Invalid UUID');
  return value;
}

function assertUUID(value: unknown): asserts value is UUID {
  if (!isUUID(value)) {
    throw new TypeError(`Expected UUID, got ${typeof value}`);
  }
}

function handleRequest(body: { id: unknown }) {
  assertUUID(body.id);
  // body.id is narrowed to UUID here
}

import { z } from 'zod';

// Zod 3
const RequestSchemaV3 = z.object({
  userId:  z.string().uuid(),
  orderId: z.string().uuid(),
});

// Zod 4
const RequestSchemaV4 = z.object({
  userId:  z.uuid(),
  orderId: z.uuid(),
});

type RequestBody = z.infer<typeof RequestSchemaV3>;

function handleRequest(body: unknown): RequestBody {
  return RequestSchemaV3.parse(body);
}

Branded Types Deep Dive

Branded types add a phantom _brand property that exists only in the type system. At runtime the value is a plain string - zero overhead, full compile-time safety.

// Generic brand helper
type Brand<T, B extends string> = T & { readonly _brand: B };

type UUID       = Brand<`${string}-${string}-${string}-${string}-${string}`, 'UUID'>;
type UserId     = Brand<UUID, 'UserId'>;
type OrderId    = Brand<UUID, 'OrderId'>;
type ProductId  = Brand<UUID, 'ProductId'>;

// Factory functions - single cast point
function newUserId():  UserId     { return crypto.randomUUID() as UserId; }
function newOrderId(): OrderId    { return crypto.randomUUID() as OrderId; }
function newProductId(): ProductId { return crypto.randomUUID() as ProductId; }

// satisfies - verify shape without widening
const config = {
  defaultUserId: newUserId(),
  maxOrders: 100,
} satisfies { defaultUserId: UserId; maxOrders: number };

Real-World Use Cases

type UserId  = string & { readonly _brand: 'UserId' };
type OrderId = string & { readonly _brand: 'OrderId' };

interface User  { id: UserId;  name: string; }
interface Order { id: OrderId; userId: UserId; total: number; }

function getOrder(id: OrderId): Promise<Order> { /* ... */ }

const userId  = crypto.randomUUID() as UserId;
const orderId = crypto.randomUUID() as OrderId;

getOrder(orderId); // ✓ OK
// getOrder(userId); // ✗ TypeScript error

import { z } from 'zod';

const ApiResponseSchema = z.object({
  id:        z.string().uuid(),
  createdAt: z.string().datetime(),
  name:      z.string(),
});

type ApiResponse = z.infer<typeof ApiResponseSchema>;

async function fetchItem(id: string): Promise<ApiResponse> {
  const res  = await fetch(`/api/items/${id}`);
  const data = await res.json();
  return ApiResponseSchema.parse(data); // throws if UUID is invalid
}

type ProductId  = string & { readonly _brand: 'ProductId' };
type CategoryId = string & { readonly _brand: 'CategoryId' };

type EntityRef =
  | { type: 'product';  id: ProductId }
  | { type: 'category'; id: CategoryId };

function resolveEntity(ref: EntityRef) {
  switch (ref.type) {
    case 'product':  return fetchProduct(ref.id);
    case 'category': return fetchCategory(ref.id);
  }
}

import { z } from 'zod';
import type { Request, Response } from 'express';

const ParamsSchema = z.object({ id: z.string().uuid() });

app.get('/users/:id', (req: Request, res: Response) => {
  const { id } = ParamsSchema.parse(req.params);
  // id is a validated UUID string
  return res.json({ id });
});

UUID v4 vs v7 Decision Guide

Use v4 by default with crypto.randomUUID(). Switch to v7 when insert order and index locality matter at database scale.

• →UUID v7 Generator - interactive v7 generation and export.
• →Format comparison - v4 vs v7 vs ULID vs NanoID.
• →JavaScript guide - runtime fundamentals and browser compatibility.

How UUID v4 Works in TypeScript

lib.dom.d.ts types crypto.randomUUID() as returning a template literal type. The OS CSPRNG fills 122 random bits; six bits encode version 4 and the RFC 4122 variant.

With 2^122 possible values, collision risk is negligible for any practical application. Branded types and Zod schemas add safety layers on top of this format without changing the underlying 128-bit structure.

Common Mistakes

Best Practices, Performance, and Security

Installation

# No installation needed for v4

npm install uuid zod
# or: pnpm add uuid zod / yarn add uuid zod

import { v7 as uuidv7 } from 'uuid';
import { z } from 'zod';
// uuid ships its own types since v9 - no @types/uuid needed

Frequently Asked Questions

Related Guides