# How to Version Runtime Types in Cloudflare Computer Projects

> Learn how Cloudflare Computer projects version runtime types automatically. Discover how deterministic hashes and CI checks ensure API consistency and prevent breaking changes.

- Repository: [Cloudflare/computer](https://github.com/cloudflare/computer)
- Tags: how-to-guide
- Published: 2026-08-15

---

**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`](https://github.com/cloudflare/computer/blob/main/worker-configuration.d.ts) file containing a **deterministic hash** that fingerprints the runtime's API surface:

```ts
// 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`](https://github.com/cloudflare/computer/blob/main/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`](https://github.com/cloudflare/computer/blob/main/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`](https://github.com/cloudflare/computer/blob/main/.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`](https://github.com/cloudflare/computer/blob/main/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`](https://github.com/cloudflare/computer/blob/main/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`](https://github.com/cloudflare/computer/blob/main/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:

```bash

# 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`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/runtime/types.ts), the hash automatically reflects the change:

```ts
// 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:

```yaml

# .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:

```ts
// 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:

```json
// 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`](https://github.com/cloudflare/computer/blob/main/worker-configuration.d.ts).
- **`wrangler types` generates this file** by inspecting [`wrangler.toml`](https://github.com/cloudflare/computer/blob/main/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`](https://github.com/cloudflare/computer/blob/main/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`](https://github.com/cloudflare/computer/blob/main/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`](https://github.com/cloudflare/computer/blob/main/worker-configuration.d.ts) file?

Manual edits are strongly discouraged. The CI pipeline in [`.github/workflows/ci.yml`](https://github.com/cloudflare/computer/blob/main/.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`](https://github.com/cloudflare/computer/blob/main/wrangler.toml) or lockfile. When one developer updates the runtime or bindings and commits the new [`worker-configuration.d.ts`](https://github.com/cloudflare/computer/blob/main/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`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/runtime/types.ts) and [`worker-configuration.d.ts`](https://github.com/cloudflare/computer/blob/main/worker-configuration.d.ts)?

[`packages/computer/src/runtime/types.ts`](https://github.com/cloudflare/computer/blob/main/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`](https://github.com/cloudflare/computer/blob/main/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.