How do I type a Cloudflare Workers fetch handler and its bindings in JavaScript?

The short answer

Describe the bindings from wrangler.jsonc in a @typedef Env, and put @satisfies {ExportedHandler<Env>} on the exported object. The example uses the Cloudflare Workers setup, with @cloudflare/workers-types in types:

/**
 * The bindings declared in wrangler.jsonc.
 * @typedef {object} Env
 * @property {KVNamespace} PRICES
 * @property {string} CURRENCY
 */

export default /** @satisfies {ExportedHandler<Env>} */ ({
  async fetch(request, env, ctx) {
    const url = new URL(request.url);
    const sku = url.searchParams.get("sku");
    if (!sku) return new Response("Missing sku", { status: 400 });

    const cents = await env.PRICES.get(sku);
    if (cents === null) return new Response("Not found", { status: 404 });

    ctx.waitUntil(Promise.resolve(console.log(`price lookup ${sku}`)));
    return Response.json({ sku, cents: Number(cents), currency: env.CURRENCY });
  },
});

interface Env {
  PRICES: KVNamespace;
  CURRENCY: string;
}

export default {
  async fetch(request, env, ctx) {
    const url = new URL(request.url);
    const sku = url.searchParams.get("sku");
    if (!sku) return new Response("Missing sku", { status: 400 });

    const cents = await env.PRICES.get(sku);
    if (cents === null) return new Response("Not found", { status: 404 });

    ctx.waitUntil(Promise.resolve(console.log(`price lookup ${sku}`)));
    return Response.json({ sku, cents: Number(cents), currency: env.CURRENCY });
  },
} satisfies ExportedHandler<Env>;

request is a Request, env has PRICES and CURRENCY, and ctx has waitUntil. The handler must return a Response (or a promise of one), and env.PRICES.get() returns Promise<string | null>.

Why it works

ExportedHandler<Env> is the type @cloudflare/workers-types gives the default export of a module that handles requests: an object whose fetch method receives the request, your bindings and an execution context. The type argument is your Env, so every binding is checked by name and type. @satisfies (TypeScript 5.0 and later) types the method’s parameters from that, without changing the export.

The Env typedef is a promise, not a check: it must match the bindings in wrangler.jsonc, and nothing compares the two unless you generate the types with wrangler types.

The same thing in TypeScript

The TypeScript equivalent tab declares interface Env and ends the object with satisfies ExportedHandler<Env>, the operator form of the same check.

What goes wrong

A misspelled binding is caught with a suggestion (TS2551), a value that may be null must be checked (TS18047), and returning a string instead of a Response fails on the method itself (TS2322):

/**
 * @typedef {object} Env
 * @property {KVNamespace} PRICES
 */

export default /** @satisfies {ExportedHandler<Env>} */ ({
  async fetch(request, env) {error TS2322: Type '(request: Request<any, IncomingRequestCfProperties<any>>, env: Env) => Promise<string>' is not assignable to type 'ExportedHandlerFetchHandler<Env, any, any>'.
  Type 'Promise<string>' is not assignable to type 'Response | Promise<Response>'.
    Type 'Promise<string>' is not assignable to type 'Promise<Response>'.
      Type 'string' is not assignable to type 'Response'.
    const fallback = await env.PRICE.get("default");error TS2551: Property 'PRICE' does not exist on type 'Env'. Did you mean 'PRICES'?
    const cents = await env.PRICES.get(new URL(request.url).pathname);
    return `${cents.length} digits, fallback ${fallback}`;error TS18047: 'cents' is possibly 'null'.
  },
});

Gotchas

• skipLibCheck stays on. The setup page’s config sets it, so tsc does not spend time checking the large runtime declaration files.
• No @types/node by default. The runtime is not Node.js; Node.js APIs need the compatibility flag in your Wrangler config and their own types, per Cloudflare’s documentation.
• Secrets are bindings too. Per Cloudflare’s documentation, a secret set with wrangler secret put arrives on env like a variable; add it to Env as a string.