Runtime APIs
Version metadata
Read your Worker's version ID, tag, and timestamp from the version_metadata binding, which Orange computes from the bundle and the configuration.
The version_metadata binding tells your Worker which build of its code is
running. Orange fills in its id, tag, and timestamp when it starts the
Worker.
Quickstart
-
Bind the metadata
Add the binding to
wrangler.jsonc.{ "name": "my-worker", "main": "src/index.ts", "compatibility_date": "2026-09-03", "version_metadata": { "binding": "CF_VERSION_METADATA" } } -
Generate the types
orange typesaddsCF_VERSION_METADATA: WorkerVersionMetadatato yourEnvtype.orange types -
Read it in your Worker
The binding is a plain object, so you can return it as JSON.
export default { async fetch(request, env): Promise<Response> { return Response.json(env.CF_VERSION_METADATA); }, } satisfies ExportedHandler<Env>; -
Run it
Start
orange devand request the Worker. The response holdsid,tag, andtimestamp.orange dev curl localhost:8787
How it works
- Orange builds the object once, when it starts the Worker’s runtime, and injects it before your code runs.
idis a hash of your bundled Worker and its configuration. It changes only when your code or configuration changes, so use it to tell builds apart.timestampis when the runtime started.
AI context Compatibility, limits and details
Written for LLMs and coding agents: every edge case, measurement, and known deviation. You do not need it to use the feature.
Compatibility
Status: Partial. It runs in the Worker’s own process.
- Works:
env.CF_VERSION_METADATAhasid,tag, andtimestamp, with Wrangler’s types. - Differs:
idis a SHA-256 hash of your bundle and configuration, not a version UUID.tagis alwaysdev. - Missing:
ctx.version. - Migration: Not needed. The binding holds no data.
| Feature | Status | Notes |
|---|---|---|
id | Partial | 64 hex characters. Code that parses it as a UUID fails. |
tag | Partial | Always dev, also under orange serve and orange deploy. |
timestamp | Partial | An ISO timestamp of when Orange built and started the Worker, not of a version upload. |
The WorkerVersionMetadata type | Supported | orange types writes the same Env type as wrangler types, byte for byte. |
version_metadata in wrangler.toml | Supported | Read as from wrangler.jsonc. |
ctx.version | Not supported | Reads undefined. workerd has it only behind the experimental enable_version_api flag. |
Limits
The binding has no limits of its own.
How the values are set
idhashes the bundled Worker and its normalized configuration, but not the timestamp. It is not for looking up a version on Cloudflare.- A secret enters the hash by its name only, so a new secret value keeps the
same
id. timestampis set each time a runtime starts. Underorange serve, each runner sets its own, so two runners of one deployment can show different times.
Hash inputs
id is the hex SHA-256 digest of, in order:
- The string
open-orange-worker-versionand a NUL byte. - The bundle’s byte length as decimal text, and a NUL byte.
- The bundled Worker’s bytes, and a NUL byte.
- The normalized configuration: stable JSON of the bindings, the
compatibility date, the compatibility flags, the Durable Object manifest,
the environment, and the Worker name. A secret’s binding appears as
{ binding, type: "secret_text" }, without its value.
An invalid build time throws a RangeError when Orange builds the object.
Deviations
These add to the Compatibility table.
idis an Orange bundle hash, not a Cloudflare Worker version ID, so it never matches an ID that Wrangler or the Cloudflare dashboard shows.timestampis set right after Orange bundles the Worker, when the runtime starts.orange devdoes not reload on a change, so every request gets the same values until the process restarts.
Conformance
- Static conformance checks the injected object against the exact
WorkerVersionMetadatatype. - Behavioral tests check field presence, formats, property behavior, and serialization through the pinned workerd runtime.
- Unit tests in
packages/runtime-node/src/bindings/version-metadata.test.tscheck deterministic IDs, an invalid timestamp, and a change to either hash input. - An end-to-end test in
tests/cli/dev.test.tsrunsorange devwith awrangler.tomland checks the ID format, the build timestamp, thedevtag, and the same values across requests served by one runtime process. - The CLI conformance fixture requires
orange typesto match pinned Wrangler byte for byte, and proves the generatedEnvproperty is exactly the runtime factory’s result type. - Cloudflare-generated identifiers are normalized rather than compared byte for byte.