TypeScript uses the same runtime APIs as JavaScript, so crypto.randomUUID is the simplest UUID v4 generator in modern browsers and Node. Types add a little extra safety at the boundary.
Key takeaways
- crypto.randomUUID() returns a typed string with no dependency.
- In Node, import randomUUID from node:crypto.
- Check runtime support; TypeScript types do not provide missing APIs.
For implementation context, continue with JavaScript, UUID v4, and UUID Regex. These pages cover the closest generator, comparison, validation or storage decisions without repeating this guide.
Generate a UUID
In browsers, crypto.randomUUID requires a secure context such as HTTPS or localhost. In Node, import randomUUID from node:crypto; that module API was added in Node 14.17 and 15.6. The global crypto object is a separate API and is not available in every older Node release.
// Browser with HTTPS or localhost
const id: string = crypto.randomUUID();
// Node, explicit import
import { randomUUID } from "node:crypto";
const nodeId = randomUUID();A typed validation helper
This guard accepts canonical hyphenated UUIDs with versions 1 through 8 and the RFC variant. It intentionally excludes nil, max, compact and braced forms. A type guard narrows unknown to string; it does not make every string a valid UUID.
const UUID_RE =
/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
function isUuid(value: unknown): value is string {
return typeof value === "string" && UUID_RE.test(value);
}Keep validated UUIDs distinct from arbitrary strings
A branded string type helps prevent accidentally passing an unvalidated string to an API within TypeScript code. Construct the brand only after validation. Types are erased at runtime, so JSON payloads and request parameters still need checks.
For browser-only code, include DOM types in tsconfig. For Node-only code, use the node:crypto import and Node type definitions instead of relying on a browser global.
type UuidString = string & { readonly __uuid: unique symbol };
function parseUuid(value: unknown): UuidString {
if (!isUuid(value)) throw new TypeError("Invalid UUID");
return value.toLowerCase() as UuidString;
}