Fix Missing Cloudflare Workers Types After the v5 Upgrade

A Cloudflare Workers dependency update can leave TypeScript unable to find a path such as @cloudflare/workers-types/2023-07-01. The package is installed, but the dated type entrypoint is gone.

The short fix for an application is to generate types from the Wrangler configuration, point TypeScript at worker-configuration.d.ts, and remove the old dated entrypoint. A library or shared package has a different choice, so do not replace the path blindly.

Why the dated path disappeared

Cloudflare released @cloudflare/workers-types v5 on July 3, 2026. Version 5 exposes the latest stable types at the bare package path and experimental types at @cloudflare/workers-types/experimental. It removes dated entrypoints such as @cloudflare/workers-types/2022-11-30 and @cloudflare/workers-types/2023-03-01.

The current Qwik Cloudflare Workers guide still shows @cloudflare/workers-types/2023-07-01 in tsconfig.json, while Cloudflare's create-cloudflare 2.70.8 release notes say Qwik scaffolding was fixed after v5 removed the dated paths. That combination is a good reason to inspect generated and copied framework configuration after the upgrade.

Pick the replacement by what you are building

Cloudflare recommends wrangler types for Worker applications because generated declarations follow the project's compatibility date, compatibility flags, bindings, and module rules. The same documentation keeps @cloudflare/workers-types as the recommended option for libraries and shared packages that need importable Workers types.

• Worker application: generate worker-configuration.d.ts with Wrangler.
• Library or shared package: use the bare @cloudflare/workers-types import when you intentionally want the latest stable Workers type surface.
• Experimental API work: use @cloudflare/workers-types/experimental only when the code also targets the required experimental runtime behavior.

Migrate an application in four edits

1. Find the old type source

Check compilerOptions.types in every tsconfig file, triple-slash type references, and direct imports. A framework adapter can add the path in a nested configuration even when the root file looks clean.

{
  "compilerOptions": {
    "types": [
      "@cloudflare/workers-types/2023-07-01",
      "node"
    ]
  }
}

2. Generate declarations from Wrangler

For a pnpm project on Wrangler v4, remove the package if the application no longer imports it, then generate the declaration file. These commands follow Cloudflare's documented migration and are illustrative for a pnpm repository.

pnpm remove @cloudflare/workers-types
pnpm wrangler types

Wrangler writes worker-configuration.d.ts by default. Regenerate it after changing the compatibility date, flags, bindings, or module rules.

3. Point TypeScript at the generated file

{
  "compilerOptions": {
    "types": [
      "./worker-configuration.d.ts",
      "node"
    ]
  }
}

Keep node in the list only when the project uses Node types. Cloudflare specifically calls for @types/node when nodejs_compat is enabled.

4. Make stale declarations fail in CI

Commit the generated declaration if that fits the repository, then add a check before typechecking or building. Wrangler's --check flag fails when the committed file no longer matches the configuration.

{
  "scripts": {
    "cf-typegen": "wrangler types",
    "cf-typegen:check": "wrangler types --check",
    "typecheck": "pnpm run cf-typegen:check && tsc --noEmit"
  }
}

Do not swap the dated path for the bare package without deciding

Changing @cloudflare/workers-types/2023-07-01 to @cloudflare/workers-types can make the missing-path error disappear. It also changes the contract. The bare v5 package tracks the latest stable type surface, while a deployed Worker runs against the compatibility date and flags in its Wrangler configuration.

For an application, generated types keep that relationship visible. For a library, the bare package can be correct because the package is not tied to one deployed Worker configuration. Record that choice in the package instead of treating both options as equivalent fixes.

Qwik projects need one extra audit

A Qwik project can contain both a cf-typegen script and the removed dated package path. Keep the script, run it, and make tsconfig.json include the generated declaration instead of the dated package entry. Also check adapter-specific tsconfig files and any project created before the scaffolding fix.

After the edit, run the project's normal typecheck and production build. The goal is not only to silence a resolver error. The generated declarations should describe the Worker that the repository is configured to deploy.

A short verification checklist

1. Search every TypeScript configuration and source file for @cloudflare/workers-types/ followed by a date.
2. Confirm the Wrangler compatibility date, flags, and bindings are the ones the application intends to deploy.
3. Run wrangler types and inspect the generated file path before changing tsconfig.json.
4. Run the normal typecheck and production build, then add wrangler types --check to CI.
5. If the Wrangler file itself needs a pull request gate, use the Wrangler configuration CI guide to check bindings, environments, and risky resource reuse separately from type generation.

The v5 change removes an old way of selecting runtime types. For an application, let Wrangler generate the type contract from the same configuration that controls deployment. That fixes the missing path and makes the next compatibility change reviewable.