cloudflare-workers-knowledge-patch

# Cloudflare Workers Knowledge Patch Use this skill when implementing, migrating, testing, or deploying Cloudflare Workers. Start with the compatibility date and Wrangler configuration, then open only the reference files relevant to the task. ## Reference index | Reference | Topics | | --- | --- | | [runtime-compatibility.md](references/runtime-compatibility.md) | Compatibility gates, Fetch and Cache behavior, JavaScript and stream APIs, Access, tracing, Dynamic Workers | | [nodejs-compatibility.md](references/nodejs-compatibility.md) | `nodejs_compat`, process and environment behavior, native APIs, stubs, timers, runtime types | | [rpc-and-websockets.md](references/rpc-and-websockets.md) | Workers RPC capabilities and ownership, pipelining, cross-language calls, WebSocket behavior | | [static-assets-and-pages-migration.md](references/static-assets-and-pages-migration.md) | Static Assets routing and deployment, Pages migration, preview and domain caveats | | [vite-development-and-testing.md](references/vite-development-and-testing.md) | Vite plugin configuration, auxiliary Workers, production-build integration tests, local traces | | [wrangler-and-deployment.md](references/wrangler-and-deployment.md) | Wrangler v4 migration, local versus remote resources, authentication, types, startup inspection, Builds | ## Triage compatibility-date changes first Before changing code, read `compatibility_date` and `compatibility_flags` from the active Wrangler configuration. Many runtime differences below are date gated and have explicit rollback flags. For dates from `2026-08-04`, Node.js compatibility is on by default. Opting out requires both flags: ```jsonc { "compatibility_date": "2026-08-04", "compatibility_flags": ["no_nodejs_compat", "no_nodejs_compat_v2"] } ``` Earlier dates do not change. Positive Node.js compatibility flags on a new date are redundant and local tooling may ignore them. When upgrading an existing Worker, specifically regression-test: - `process.env` population at `2025-04-01` with `nodejs_compat`. - Static Asset navigation fallback ordering at `2025-04-01`. - cross-origin `Authorization` stripping at `2025-09-01`. - optional runtime properties becoming present with `undefined` at `2025-12-03`. - `require()` default-export interop at `2026-01-22`. - iterable request and response bodies at `2026-02-19`. - WebSocket close, binary, and half-open behavior in March 2026. - Node-compatible timer handles at `2026-02-10`. See [runtime compatibility](references/runtime-compatibility.md) and [Node.js compatibility](references/nodejs-compatibility.md) for flags and edge cases. ## Migrate to Wrangler v4 Wrangler v4 requires a supported Node.js release and no longer supports Node.js 16. Its bundled esbuild moved from 0.17.19 to 0.24; minor Wrangler updates may also move pre-1.0 esbuild versions and alter bundling. Wildcard dynamic imports include every matching file, so inspect bundle contents. Replace removed commands and settings: | Removed or deprecated | Use | | --- | --- | | `legacy_assets` | Static Assets | | `node_compat` | `nodejs_compat` | | `getBindingsProxy()` | `getPlatformProxy()` | | `wrangler publish` | `wrangler deploy` | | `wrangler pages publish` | `wrangler pages deploy` | | `wrangler generate` | `npm create cloudflare@latest` | | `wrangler version` | `wrangler --version` | | `usage_model` | Remove it; it has no effect | Workers Sites and service environments using `legacy_env` are deprecated; prefer Static Assets and Wrangler environments. Resource commands default to local operation. Add `--remote` when a command must operate on account data: ```sh wrangler kv key get --binding MY_KV "my-key" --remote ``` Read [Wrangler and deployment](references/wrangler-and-deployment.md) before changing authentication, generated types, Builds, or deployment commands. ## Configure Static Assets deliberately `assets.directory` deploys static files and Worker code together. Exact asset matches bypass the Worker by default; misses invoke `main`. Add an asset binding only when Worker code must delegate to the asset service: ```jsonc { "main": "src/index.js", "assets": { "directory": "./dist", "binding": "ASSETS", "not_found_handling": "single-page-application", "run_worker_first": ["/api/*", "!/api/docs/*"] } } ``` An assets-only Worker must omit `binding`. Unlike Pages, Workers does not infer SPA or 404 behavior, so set `not_found_handling`. From `2025-04-01`, navigation fallback can run before the Worker unless `run_worker_first` applies. For a Pages migration, preserve the compatibility date, replace `pages_build_output_dir` with `assets.directory`, and explicitly recreate function-first routes. See [Static Assets and Pages migration](references/static-assets-and-pages-migration.md). ## Choose the right development and test path The Cloudflare Vite plugin executes application code in `workerd` while retaining Vite HMR: ```ts import { cloudflare } from "@cloudflare/vite-plugin"; import { defineConfig } from "vite"; export default defineConfig({ plugins: [cloudflare()] }); ``` Requests enter through the main Worker even when `auxiliaryWorkers` are configured. Builds emit separate subdirectories, and each auxiliary Worker must be deployed separately. Use Wrangler's `createTestHarness()` for integration tests against production builds. It supersedes `unstable_startWorker()` and `unstable_dev()` and can dispatch requests, reset storage, expose logs, mock outbound requests, and integrate with Playwright. See [Vite development and testing](references/vite-development-and-testing.md) for configuration precedence, persisted state, inspector defaults, tunnels, and harness lifecycle. ## Use RPC as capability-based async calls RPC requires compatibility date `2024-04-03` or later, or the `rpc` flag. Public `WorkerEntrypoint` methods are callable through Service Bindings and Durable Object methods through object bindings. Every remote call is async, even when the implementation is synchronous. Functions become callable stubs in their originating Worker. Classes crossing RPC must extend `RpcTarget`; accessing a remote property also requires `await`. Prefer one `RpcTarget` over plain objects containing many functions, because each plain function creates a separate stub. Use promise pipelining to avoid an unnecessary round trip: ```ts using pendingCounter = env.COUNTERS.create(); await pendingCounter.increment(); ``` Streams, `Request`, and `Response` transfer ownership. Clone or `tee()` values that the sender still needs. Forwarded stubs cannot be persisted beyond the participating execution contexts. RPC ignores Smart Placement. Read [RPC and WebSockets](references/rpc-and-websockets.md) for stub lifetime, parameter duplication, message limits, Python interoperability, and WebSocket compatibility gates. ## Handle WebSocket gates explicitly The maximum WebSocket message size is 32 MiB. Client failures surface as catchable JavaScript exceptions. From `2026-03-03`, close reasons over 123 UTF-8 bytes throw `SyntaxError`. From `2026-03-10`, receipt of a Close frame sends the reciprocal frame and marks the socket closed before the event. A proxy requiring the old half-open phase must accept an upgrade-created socket with `{ allowHalfOpen: true }`. From `2026-03-17`, `binaryType` defaults to `"blob"`. Set it to `"arraybuffer"` before `accept()` when needed. Hibernatable Durable Object handlers continue receiving `ArrayBuffer`. ## Generate runtime types from configuration Prefer `wrangler types` so declarations match the Worker's compatibility date, flags, bindings, and module rules: ```sh wrangler types wrangler types --check ``` Include `worker-configuration.d.ts` through `compilerOptions.types`; add `@types/node` with Node.js compatibility. The root of `@cloudflare/workers-types` v5 contains current stable types, experimental APIs live under `/experimental`, and dated package entrypoints no longer exist. ## Validate before deployment 1. Confirm the active Wrangler configuration and compatibility date. 2. Run `wrangler types --check` when generated declarations are committed. 3. Exercise the production bundle through `createTestHarness()`. 4. Inspect startup cost with `wrangler check startup` when initialization is material. 5. Use local trace and log correlation to find binding and subrequest latency. 6. Deploy auxiliary Workers individually, then deploy the entry Worker. 7. Pass `--remote` only for resource commands intentionally targeting account data.