The config that types itself

Build a config and watch three things move

Toggle bindings on the left. The middle pane is the config you would write, in the shape that builds today. The right pane switches between what the platform receives and what your env becomes. Every row below was measured through a real Worker on 2026-10-05: the resolved JSON is what wrangler build --x-new-config --x-cf-build-output wrote, and each type is what the compiler reported for that key of the generated interface.

The two front doors agree. cf build (1.0.0-beta.12) printed "Delegating to Wrangler" and wrote the same four files wrangler build did, sha256 for sha256. The snippet imports from @cloudflare/config/public, as this site's own cloudflare.config.ts does. The documentation's cf/config re-exports that module in one line, so either import works, and the resolved output is identical.

One trap sits between the build and the types. The generated .cloudflare/types/index.d.ts imports cf/config. Install wrangler and @cloudflare/config without cf, keep skipLibCheck on as most templates do, and nothing complains: Env comes back empty, and every binding read is TS2339 on a value typed any. Only with skipLibCheck off does TS2307 name the missing module. Add cf as a dev dependency, as the docs say, or map cf/config in paths, which is what this site does.

A variable arrives in the type as its own value, in both formats

Thirteen binding kinds went through the compiler. Most land where you would guess, and three carry more than a bare type.

bindings.text("default") gives env.AI_GATEWAY the type "default", so the variable's value is in the type and a comparison against a string that was never configured is a compile error. bindings.json({ dcz: true, tier: 2 }) comes back as { dcz: true; tier: number }, where the boolean narrows to a literal and the number widens, which is ordinary TypeScript inference showing through. And bindings.secret() types the secret as string, so a secret you forgot to set is a name the compiler already knows about.

This section used to say a JSON config structurally cannot do this. That was wrong, and it was already wrong on 4.125.0. Run against an equivalent wrangler.jsonc, wrangler types writes AI_GATEWAY: "default" on both 4.125.0 and 4.147.0. It types the required secret as string too, and it narrows the JSON variable further than inference does, to {"dcz":true,"tier":2}. What the TypeScript config changes is when the type is computed. wrangler types takes a snapshot that the reminder above asks you to retake. The inferred Env reads the config every time the compiler runs, so a renamed binding is a type error with no regeneration step.

One row is new since August. bindings.analyticsSQL(), added in config 0.22.0, resolves to {"type":"analytics"} and types as AnalyticsSQLBinding. Wrangler 4.147.0 builds it. cf 1.0.0-beta.5, which carries config 0.20.0, lets wrangler write the build output and then refuses that output on its own schema check, with "Invalid discriminator value", and exits 1. Beta.12 accepts it.

The row that went backwards, and the way around it

The Durable Object type is where the new format lost in August, and the October run found a way around it that works for some Workers and leaves the rest where they were. Against a JSON config, wrangler types threads the class through, on 4.147.0 as on 4.125.0:

COUNTER: DurableObjectNamespace<import("./src/index").Counter>;
BOOKING: Workflow<Parameters<import("./src/index").Booking['run']>[0]['payload']>;

Under inference, a binding that names its Worker by string still comes back as DurableObjectNamespace<undefined>, so a stub method call fails with Property 'increment' does not exist on type 'DurableObjectStub<undefined>'. That holds with the entrypoint given as a path string and with it given as a module through the { type: "cf-worker" } import attribute, the same two forms August tried.

What changed is the binding helper. Its worker option (spelled workerName in August) now takes either a name or a Worker definition. Bind a class that a second Worker exports, pass that Worker's definition, and give that definition a module entrypoint:

import * as counterModule from "./src/index.ts" with { type: "cf-worker" };

export const counterWorker = defineWorker({
  name: "probe-counter",
  entrypoint: counterModule,
  exports: { Counter: exports.durableObject({ storage: "sqlite" }) },
});

// in the binding Worker's env:
COUNTER: bindings.durableObject({ worker: counterWorker, exportName: "Counter" }),

Now env.COUNTER types as DurableObjectNamespace<Counter>, and await stub.increment(1) is a number the compiler checks. A Workflow bound the same way types as Workflow<{ slot: string }>. The resolved JSON is the same as the string form, "worker": "probe-counter", so the definition buys a type and changes nothing the platform receives.

Two controls say which half does the work. The same definition with a path-string entrypoint gives DurableObjectNamespace<DurableObjectBranded>, which still has no methods, so the module import is load-bearing. And a Worker that binds its own class cannot take this route: pointing the binding at its own definition through a factory is circular, tsc reports TS7022, and the binding collapses to never. One more thing the build does not do is type-check the config. A Workflow binding whose exportName the definition did not declare was a compile error, and wrangler build still exited 0.

So the scoreboard moved. Cross-Worker Durable Objects and Workflows now type as precisely as wrangler types types them, and stay current without a regeneration step. A Worker that binds its own Durable Object, the common single-Worker case, still types worse than the snapshot does.

Migrations become a state on an export

The cumulative migration list is gone. A class declares what it is on its own export, and the storage engine sits beside it:

This is a different upload path. Wrangler 4.147.0 still decides between them in one function, resolveDoLifecyclePayload: when a config declares Durable Object exports it sends those exports and sends no migrations at all, and it computes a migration only for configs that declare none.

In August that left one question a dry run structurally cannot answer, because a dry run never computes a migration: would the API accept the export form for a class that already exists under an applied migration tag? This site's demo Worker answered it on 2026-09-21. It deployed on this format (wrangler 4.136.0, pin b168333) against a Counter created under tag = "v1", the API accepted it, and the counter read 18 and then 20 on the calls after, where a recreated namespace would have restarted from 0. That answer covers wrangler deploy. It says nothing about versions upload, which refuses Durable Object lifecycle changes on its own path.

One thing it still will not do, and one it now does

The dependency instrumentation key still has no home. The old config set [dependencies_instrumentation] enabled = true, and config 0.23.0 has no field for it. The escape hatch offers no route around it, because unsafe carries metadata and capnp schemas alone. This cost nothing, for a reason only readable in wrangler's source: 4.147.0 still tests the key as enabled !== false, so an absent block behaves exactly like the explicit true. A dry run reports on none of this, which is why the answer came from reading the upload path.

The types file now comes from a build. wrangler types --x-new-config still fails, with "Unknown arguments: x-new-config, xNewConfig". In August the generated file came only from wrangler dev, so the inferred types existed on a machine somebody had run the dev server on. On 4.147.0, wrangler build --x-new-config --x-cf-build-output writes it too, and so do cf build and cf workers types, which wrote the same 622,861 bytes. That is the build step this page asked for in August.

The bun trap, and why it is a trap

The loader refuses bun, in a message that names itself, and on 4.147.0 a second warning follows it:

cloudflare.config.ts loading is not supported on Bun. Please use Node.js v22.18.0 or higher.
Wrangler does not support the Bun runtime. Please try this command again using Node.js via `npm` or `pnpm`.

On a repository whose whole toolchain is bun, that reads as a blocker for about a minute. It is a claim about the process that ends up running wrangler, and the package manager that launched it does not enter into it. Re-run on bun 1.4.3-canary.1:

The first two resolve node_modules/.bin/wrangler, whose #!/usr/bin/env node shebang hands the process to node before any config is read. The last two put bun in front of the loader, one by overriding the shebang and one by running wrangler's entry file directly. So "does this tool support bun" turned out to be a question about a shebang, and the answer changed with the invocation while the tool stayed the same.

What this cost, and what it did not

The conversion ran first on this site's smallest deployed Worker, the one behind /garage/cf/*, chosen because it is a demo that a person deploys by hand. In August the upload came out at 8.83 KiB, 3.07 KiB gzip, the same as before to the byte, with the same four bindings. Re-measured on 4.147.0 against the old wrangler.toml with its flags and minify setting brought level, both configs produce the same index.js, sha256 for sha256, at 5.94 KiB, 2.63 KiB gzip. The source maps differ only in their output-relative paths.

In August the main Worker still typed env as any, because converting it meant folding two config files of 24,662 and 10,987 bytes into one program and putting a hidden flag on the path that publishes production. It moved on 2026-09-28, with an upload byte-identical to the JSON's. Its handlers take env: Env now, from a hand-written interface that a check diffs against cloudflare.config.ts in both directions. That choice is about optional secrets, which the interface marks with ? so every read has to face their absence, and about the Durable Object: its Counter lives in a second Worker that still has a wrangler.jsonc, so there is no definition to import yet.

What would change the verdict

Two of August's three triggers have fired. The API accepted the export-based Durable Object form on a real deploy, so the migration table is a translation. Documentation arrived, though the flag stayed hidden and the documented door became cf.

The third half-fired: the class type now threads through a binding to another Worker. What would finish it is a self-bound Durable Object that types as its class, which would remove the last column where wrangler types wins. The other result worth watching is the format leaving open beta, since several shapes on this page moved between the two runs: the import path, the default export, the Durable Object binding key and the build output file.

watching · the understanding check is part of the page, not a gate