Skip to content
Runtime APIs / Version metadata

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

  1. 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" }
    }
  2. Generate the types

    orange types adds CF_VERSION_METADATA: WorkerVersionMetadata to your Env type.

    orange types
  3. 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>;
  4. Run it

    Start orange dev and request the Worker. The response holds id, tag, and timestamp.

    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.
  • id is 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.
  • timestamp is 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_METADATA has id, tag, and timestamp, with Wrangler’s types.
  • Differs: id is a SHA-256 hash of your bundle and configuration, not a version UUID. tag is always dev.
  • Missing: ctx.version.
  • Migration: Not needed. The binding holds no data.
FeatureStatusNotes
idPartial64 hex characters. Code that parses it as a UUID fails.
tagPartialAlways dev, also under orange serve and orange deploy.
timestampPartialAn ISO timestamp of when Orange built and started the Worker, not of a version upload.
The WorkerVersionMetadata typeSupportedorange types writes the same Env type as wrangler types, byte for byte.
version_metadata in wrangler.tomlSupportedRead as from wrangler.jsonc.
ctx.versionNot supportedReads 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

  • id hashes 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.
  • timestamp is set each time a runtime starts. Under orange 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:

  1. The string open-orange-worker-version and a NUL byte.
  2. The bundle’s byte length as decimal text, and a NUL byte.
  3. The bundled Worker’s bytes, and a NUL byte.
  4. 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.

  • id is an Orange bundle hash, not a Cloudflare Worker version ID, so it never matches an ID that Wrangler or the Cloudflare dashboard shows.
  • timestamp is set right after Orange bundles the Worker, when the runtime starts.
  • orange dev does 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 WorkerVersionMetadata type.
  • 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.ts check deterministic IDs, an invalid timestamp, and a change to either hash input.
  • An end-to-end test in tests/cli/dev.test.ts runs orange dev with a wrangler.toml and checks the ID format, the build timestamp, the dev tag, and the same values across requests served by one runtime process.
  • The CLI conformance fixture requires orange types to match pinned Wrangler byte for byte, and proves the generated Env property is exactly the runtime factory’s result type.
  • Cloudflare-generated identifiers are normalized rather than compared byte for byte.