Cloudflare Workers now ships crypto.randomUUIDv7() as a first-class built-in API. For teams generating identifiers at the edge — request IDs, trace correlation tokens, event keys — this removes the last remaining reason to bundle any UUID library. The function is available under compatibility date 2026-03-01 and later, returning a lowercase hyphenated string conforming to RFC 9562 §5.7.
What the API looks like
The API mirrors crypto.randomUUID() exactly, differing only in the name:
export default {
async fetch(request: Request, env: Env): Promise<Response> {
const traceId = crypto.randomUUIDv7();
// e.g. "019236a7-b4f2-7000-8d3e-9c1a2b3d4e5f"
const body = JSON.stringify({ traceId });
return new Response(body, {
headers: {
"Content-Type": "application/json",
"X-Trace-Id": traceId,
},
});
},
};
The return value is a string such as 019236a7-b4f2-7000-8d3e-9c1a2b3d4e5f. The first 12 hex characters encode 48 bits of Unix timestamp in milliseconds. This timestamp prefix is what makes UUID v7 values sort chronologically — both as strings and as binary — without any secondary created_at column.
Enabling it in wrangler.toml
The API gates behind the Workers compatibility date system. Set the date to 2026-03-01 or any later date:
# wrangler.toml
name = "my-worker"
main = "src/index.ts"
compatibility_date = "2026-03-01"
Workers with an older compatibility_date do not have crypto.randomUUIDv7() in scope. If you try to call it without the correct date, you will receive a TypeError: crypto.randomUUIDv7 is not a function at runtime. The fix is to bump the compatibility date and retest your Worker against the compatibility changelog.
Why this matters at the edge
Edge runtimes have a different cost model from Node.js. Bundle size contributes to startup latency, and every imported npm module adds to the serialised script size. Before this change, the recommended approach was:
| Approach | Bundle cost | Works without npm? |
|---|---|---|
uuid npm package (uuidv7()) | ~3 KB minified | No |
| Custom inline implementation | ~1 KB | Yes, but maintenance burden |
crypto.randomUUID() (v4) | 0 KB | Yes, but not time-sortable |
crypto.randomUUIDv7() (native) | 0 KB | Yes, time-sortable |
The native API is the zero-cost choice. It is also the safest: the implementation is maintained by Cloudflare inside the V8 isolate, so there are no supply-chain risks from a third-party npm package.
Using UUID v7 as a Durable Object key
One of the strongest use cases at the edge is keying Durable Objects. Because Durable Objects route by string ID, using a time-sortable key gives you chronological ordering for free when listing stored keys:
export default {
async fetch(request: Request, env: Env): Promise<Response> {
const sessionId = crypto.randomUUIDv7();
// Create or retrieve the Durable Object for this session
const id = env.SESSIONS.idFromName(sessionId);
const stub = env.SESSIONS.get(id);
return stub.fetch(request);
},
};
When you use list() on a Durable Object namespace or a KV namespace whose keys begin with UUID v7 values, results come back in creation order naturally. This is the same benefit that UUID v7 brings to B-tree database indexes — discussed in depth at UUID in Databases.
Comparing crypto.randomUUID vs crypto.randomUUIDv7
Both functions are available in the Workers runtime under the same compatibility date requirements. The distinction is purely in what data the UUID encodes:
| Property | crypto.randomUUID() | crypto.randomUUIDv7() |
|---|---|---|
| Version bits | 4 | 7 |
| Timestamp prefix | No | 48-bit Unix ms |
| Chronological sort | No | Yes |
| Entropy bits | 122 | 74 |
| Use case | Opaque IDs, security tokens | DB primary keys, event IDs, log correlation |
The reduced entropy in UUID v7 (74 bits vs 122 bits for v4) is not a practical concern for most applications — 74 bits of randomness still makes collisions astronomically unlikely. See the UUID validator to inspect the version and variant bits of any UUID.
Migrating from the uuid npm package
If your Worker currently imports from the uuid package, the migration is a one-line change:
// Before
import { v7 as uuidv7 } from "uuid";
const id = uuidv7();
// After
const id = crypto.randomUUIDv7();
Remove the uuid import and the package from package.json. Rebuild and redeploy. The output format is identical — lowercase hyphenated string, 36 characters, RFC 9562-compliant.
Further reading
- UUID v7 generator — generate RFC 9562-compliant UUID v7 values in the browser
- UUID in JavaScript — uuid npm package, crypto.randomUUID, Workers, and Node.js patterns
- RFC 9562 glossary entry — the current UUID specification that defines v7
External references
- Cloudflare Workers Web Crypto API docs: official documentation for crypto.randomUUID() and crypto.randomUUIDv7() in the Workers runtime
- Cloudflare Workers compatibility dates: the full changelog of runtime changes gated by compatibility date
- github.com/cloudflare/workerd: the open-source Workers runtime — source for the crypto.randomUUIDv7() implementation
- Cloudflare blog — UUID v7 native support in Workers: the announcement post covering motivation, implementation details, and migration guidance
Frequently asked questions
Can I use crypto.randomUUIDv7() in Cloudflare Workers today?
Yes. The Cloudflare Workers runtime added crypto.randomUUIDv7() in the compatibility date 2026-03-01. Set compatibility_date = "2026-03-01" or later in your wrangler.toml to enable it. Workers on older compatibility dates continue to use the polyfill path.
Does crypto.randomUUIDv7() work in Cloudflare Pages Functions?
Yes. Pages Functions share the Workers runtime, so crypto.randomUUIDv7() is available under the same compatibility date requirement. No additional configuration is needed beyond setting the compatibility date in your pages project settings.
Is the generated UUID v7 monotonic within a single Worker invocation?
Yes. The Workers runtime implements the Method 1 monotonic counter from RFC 9562 §6.2, so multiple calls within the same millisecond increment a sub-millisecond counter rather than resetting to a random value. Across separate invocations, ordering is determined by wall-clock time.
What should I use if I need to support older compatibility dates?
Use the uuid npm package and call uuidv7() from it. The bundle cost is minimal and the output is identical in format to the native API.