How to Version Runtime Types in Cloudflare Computer Projects

Cloudflare Computer projects version runtime types automatically through a deterministic hash embedded in the wrangler types generated file, enforced by CI checks that fail when the runtime API surface changes.

Cloudflare Computer provides a sandboxed runtime for executing Workers code. The public API surface—classes, interfaces, and type aliases—is expressed as runtime types that must stay synchronized with the actual runtime implementation. According to the cloudflare/computer source code, this synchronization is achieved through an automatic versioning scheme built into the Wrangler CLI.

How Runtime Type Versioning Works

The Hash-Based Versioning Mechanism

Each time you run wrangler types, Wrangler generates a worker-configuration.d.ts file containing a deterministic hash that fingerprints the runtime's API surface:

// Generated by Wrangler by running `wrangler types` (hash: 5dda3fc9ced7f7fb0ae2e00843df5dec)

This hash is computed from the canonicalized output of the type generation process. Any change to the runtime—new APIs, removed APIs, or altered signatures—produces a new hash. This creates a traceable version for every commit without requiring explicit version numbers.

The Type Generation Pipeline

The versioning process follows five steps as implemented in the Cloudflare Computer repository:

• Step 1: Configuration Inspection — Wrangler reads wrangler.toml (or wrangler.jsonc) to determine the Worker's environment and target runtime.

• Step 2: Type Generation — Wrangler invokes the runtime's type-gen tool (workerd v1.20260616.1) to emit the full TypeScript declaration file to examples/think/worker-configuration.d.ts.

• Step 3: Hash Computation — A hash is prepended to the file based on canonicalized output, ensuring any runtime change produces a detectable difference.

• Step 4: CI Enforcement — The .github/workflows/ci.yml matrix runs npx wrangler types for each example and compares the new hash to the committed one. A mismatch fails the pipeline.

• Step 5: Type Consumption — Application code imports generated types (Env, GlobalProps, WorkerGlobalScope) from examples/think/src/index.ts for accurate IntelliSense.

Core Runtime Types vs. Generated Types

The Cloudflare Computer architecture separates stable runtime protocol types from generated environment types:

• packages/computer/src/runtime/types.ts (lines 1-200): Defines the low-level protocol used by the computerd client and Durable Object RPC layer. These are stable across builds and version-agnostic.

• worker-configuration.d.ts: Re-exports runtime types plus environment-specific bindings, with the hash providing version tracking.

Regenerating and Updating Runtime Types

When you modify the runtime, follow this workflow to update the versioned types:

# 1. Navigate to your project (e.g., the "think" example)

cd examples/think

# 2. Regenerate types with Wrangler

npx wrangler types

# 3. Verify the hash changed

git diff worker-configuration.d.ts

# 4. Commit the updated file

git add worker-configuration.d.ts && git commit -m "chore: update runtime types for new API"

Example: Adding a New Runtime Method

When extending the runtime in packages/computer/src/runtime/types.ts, the hash automatically reflects the change:

// packages/computer/src/runtime/types.ts
export interface WorkspaceRuntime {
  // Existing members ...
  
  /** New API introduced in workerd v1.20260701.0 */
  reloadModule(moduleName: string): Promise<void>;
}

After running wrangler types, the generated file receives a new hash that CI verifies.

Enforcing Version Consistency in CI

The Cloudflare Computer repository uses GitHub Actions to enforce that committed hashes match the current runtime:

# .github/workflows/ci.yml

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Install dependencies
        run: npm ci
      
      - name: Generate types for each example
        run: |
          for ex in examples/*; do
            (cd "$ex" && npx wrangler types) || exit 1
          done
      # If any hash changed, git status will be dirty and the job fails

This guarantees that every commit touching the runtime is accompanied by matching type definitions.

Using Versioned Types in Worker Code

Import the generated types to get accurate IntelliSense for your runtime environment:

// examples/think/src/index.ts
import type { Env, GlobalProps } from "./worker-configuration.d.ts";

export default {
  async fetch(request: Request, env: Env, ctx: ExecutionContext) {
    // `env` has proper types for AI bindings, DurableObjectNamespace, etc.
    const result = await env.AI.run("@cf/meta/llama-3-8b", {
      prompt: "Hello, world!"
    });
    return new Response(JSON.stringify(result));
  },
};

Alternative generation for projects with environment files:

// examples/tutorial/package.json
{
  "scripts": {
    "build:types": "wrangler types --env-file=.env.example"
  }
}

Summary

• Runtime types in Cloudflare Computer are versioned automatically via a deterministic hash in worker-configuration.d.ts.
• wrangler types generates this file by inspecting wrangler.toml and calling the workerd type-gen tool.
• The hash changes whenever the runtime API surface changes, providing cheap, traceable versioning without manual version numbers.
• CI enforces consistency by regenerating types and failing if the hash diverges from the committed file.
• Core protocol types live in packages/computer/src/runtime/types.ts and remain stable, while generated files re-export them with environment-specific bindings.

Frequently Asked Questions

What triggers a hash change in worker-configuration.d.ts?

Any modification to the runtime's public API surface triggers a new hash. This includes adding or removing methods on WorkspaceRuntime, changing function signatures, or updating type aliases. The hash is computed from the canonicalized TypeScript output, so even whitespace-normalized changes to the API structure produce a different fingerprint.

Can I manually edit the generated worker-configuration.d.ts file?

Manual edits are strongly discouraged. The CI pipeline in .github/workflows/ci.yml regenerates the file and compares hashes; any discrepancy fails the build. If you need custom type extensions, create a separate declaration file that augments the generated types rather than modifying the generated file directly.

How do I handle version mismatches between team members?

Ensure all developers use the same workerd version specified in your wrangler.toml or lockfile. When one developer updates the runtime or bindings and commits the new worker-configuration.d.ts, others must pull those changes before running wrangler types locally. The hash serves as a synchronization checkpoint across the team.

What's the difference between packages/computer/src/runtime/types.ts and worker-configuration.d.ts?

packages/computer/src/runtime/types.ts defines the core protocol types used internally by the computerd client and RPC layer—these are stable implementation details. worker-configuration.d.ts is the generated consumer API that combines runtime types with environment-specific bindings (KV, Durable Objects, AI) and includes the version hash for tracking compatibility.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}