skip to content

In a TypeScript Cloudflare Worker, what does `wrangler types` generate from the Wrangler file, and how does it type vars and secrets?

level: middleimportance: should knowfreq 28%

answer

  1. a generated declaration file
  2. Env interface from the bindings
  3. literal types for vars
  4. the secrets.required names
  5. --check in CI

basics

~20 s

wrangler types writes worker-configuration.d.ts with an Env interface listing every binding's type, plus runtime types for the compatibility date. Vars get literal types by default; secrets are typed string, named from secrets.required when it is declared.

solid answer

~40 s

In Wrangler 4, `wrangler types` reads the Wrangler file and writes `worker-configuration.d.ts` by default. It declares an `Env` interface, also merged into `Cloudflare.Env` so the imported `env` is typed, with one member per binding: `KVNamespace`, `R2Bucket`, `SecretsStoreSecret` and so on. It also emits runtime types for the Worker's compatibility date and flags, which is why Cloudflare recommends it over the `@cloudflare/workers-types` package for a Worker. Vars get literal types because `--strict-vars` defaults to true, so `"REFUNDS_ENABLED": "false"` becomes the type `"false"`; `--strict-vars=false` widens them to `string`, `number` or `object`. Secrets are typed `string`: when the file declares `secrets.required`, those names are the source; otherwise Wrangler infers them from local secret files. Rerun it after every config change, and run `wrangler types --check` in CI so a stale file fails the build.

code

typescript · 14 lines
typescript
// Excerpt of worker-configuration.d.ts (generated; do not edit)
interface __BaseEnv_Env {
	WEBHOOK_STATE: KVNamespace;
	RECEIPTS: R2Bucket;
	SIGNING_KEY: SecretsStoreSecret;
	REFUNDS_ENABLED: "false";
	RETRY_LIMIT: 3;
	PROVIDER: {"region":"eu","timeoutMs":2500};
	PROVIDER_API_KEY: string;
}
declare namespace Cloudflare {
	interface Env extends __BaseEnv_Env {}
}
interface Env extends __BaseEnv_Env {}

go deeper

for a junior

Recall that wrangler types writes worker-configuration.d.ts with an Env interface, used as ExportedHandler<Env> on the default export.

for a middle

Explain how bindings, literal var types and secrets.required become members of Env, and what --strict-vars=false changes.

for a senior

Keep types honest with wrangler types --check in CI, and extend Env through declaration merging instead of editing generated code.

for a principal

Decide whether the generated file is committed or rebuilt in CI, and make the check part of the pipeline so configuration drift fails early.

## The problem it solves A Worker's `env` object is assembled from configuration, not from code: whatever the Wrangler file declares under `kv_namespaces`, `r2_buckets`, `vars`, `secrets_store_secrets` and the other binding keys appears on `env` at run time. TypeScript cannot see that file, so without help `env` is either `any` or a hand-written interface that drifts from the configuration. **`wrangler types`** closes the gap by generating the types from the file itself. ## What the generated file contains Running `npx wrangler types` writes `worker-configuration.d.ts` (a different path can be passed as an argument). The file holds: - an **`Env` interface** with one member per binding (the name can be changed with `--env-interface`); - the same members merged into **`Cloudflare.Env`**, the interface that types `import { env } from "cloudflare:workers"`; - **runtime types** (`Request`, `Response`, `KVNamespace`, `R2Bucket` and the rest) matched to the Worker's `compatibility_date` and `compatibility_flags`, unless `--include-runtime=false` is passed; - a typed **`process.env`** view of the vars and secrets, each value typed as a string. Cloudflare recommends this over installing `@cloudflare/workers-types` for a Worker, because the generated runtime types follow the Worker's own date and flags. The package is still the recommended way to type libraries shared between Workers. The file is added to `compilerOptions.types` in `tsconfig.json`. ## How each binding is typed | Wrangler entry | Generated member | |---|---| | KV binding `WEBHOOK_STATE` | `WEBHOOK_STATE: KVNamespace` | | R2 binding `RECEIPTS` | `RECEIPTS: R2Bucket` | | Secrets Store binding `SIGNING_KEY` | `SIGNING_KEY: SecretsStoreSecret` | | var `"REFUNDS_ENABLED": "false"` | `REFUNDS_ENABLED: "false"` | | var `"RETRY_LIMIT": 3` | `RETRY_LIMIT: 3` | | secret listed in `secrets.required` | `PROVIDER_API_KEY: string` | **Vars get literal types** because `--strict-vars` defaults to true: the type records the exact value in the file. That catches real mistakes. With `REFUNDS_ENABLED` typed as `"false"`, the check `env.REFUNDS_ENABLED === "true"` fails to compile with TS2367 ("the types '"false"' and '"true"' have no overlap"). Teams that change such values often, or prefer plain types, pass `--strict-vars=false`, which types the same vars as `string`, `number` and `object`. **Secrets are typed `string`.** Their names come from one of two places: 1. If the Wrangler file declares a `secrets` property, the names in `secrets.required` are the source of truth, so types can be generated in CI where no local secret files exist. The same list makes `wrangler deploy` and `wrangler versions upload` fail when a required secret is not set on the Worker. 2. Otherwise Wrangler infers secret names from the local secret files (`.dev.vars` or `.env`) it finds. Secret values never reach the generated file; only the names do. ## Keeping the types current - **Rerun after every configuration change.** Adding a binding without regenerating leaves `env.NEW_BINDING` untyped. - **Never edit the generated file**: it is overwritten on every run. Extra members go in a source-owned declaration that merges into `Cloudflare.Env`. - **Check in CI.** `wrangler types --check` compares the existing file with what would be generated and, when they differ, exits non-zero with an error saying the types at `worker-configuration.d.ts` are out of date and asking you to run `wrangler types` to regenerate them. - **Add `@types/node`** when the Worker uses Node.js compatibility, so `node:` imports are typed. - Handlers are typed with `satisfies ExportedHandler<Env>`, which types `env` and `ctx` for every handler in the default export. ## Where it fits in a build Cloudflare's guidance is to run `wrangler types` before any task that relies on TypeScript. A common arrangement: 1. A package script such as `"generate-types": "wrangler types"` runs before the type-check script, so a fresh checkout never type-checks against missing declarations. 2. The generated file is either committed (the docs allow it), which makes binding changes visible in code review, or generated in CI, which keeps it out of diffs; `--check` suits the committed style. 3. A project that only wants binding types and supplies runtime types another way passes `--include-runtime=false`; one that only wants runtime types passes `--include-env=false`. Whichever style the team picks, the rule is the same: the Wrangler file is the single description of the bindings, and the types are derived from it rather than maintained beside it.

  • Why does `env.REFUNDS_ENABLED === "true"` fail to compile after running `wrangler types`?
    With `--strict-vars` on by default, a var declared as `"false"` is typed as the literal `"false"`, so TypeScript reports TS2367: the two literal types have no overlap. Regenerate with `--strict-vars=false` to type vars as plain `string`, or keep the literal types and treat the error as a sign that the code tests a value the configuration never sets.
  • How do you add a type that `wrangler types` cannot know about without editing the generated file?
    Use declaration merging in a source-owned `.d.ts`: `declare namespace Cloudflare { interface Env { BUILD_SHA: string } }`. The generated file is overwritten on every run, so edits there are lost, while merged declarations survive and also type the imported `env`.

  • Hand-editing worker-configuration.d.ts and expecting the edits to survive the next run.
  • Typing env as any because bindings are only known at deploy time.
  • Relying on @cloudflare/workers-types alone to match the Worker's compatibility date.
  • Adding a binding to the Wrangler file without rerunning wrangler types.
  • Expecting wrangler types to fetch secret values from the deployed Worker.

Assumes Wrangler 4.149.0 as of 2026-10-10: secrets.required is a recent Wrangler 4 config property, and @cloudflare/workers-types 5 dropped its dated entrypoints, leaving wrangler types as the way to match a compatibility date.