{"id":15288,"library":"workerd","title":"workerd Runtime","description":"Cloudflare's `workerd` is an open-source JavaScript/WebAssembly server runtime, built on the same core technology that powers Cloudflare Workers. It provides a local execution environment for developing and testing serverless applications that replicate the Cloudflare Workers platform. The current stable version, `v1.20260421.1`, follows a `v1.YYYYMMDD.X` daily release cadence, reflecting continuous integration and frequent updates with features and bug fixes. Key differentiators include its high compatibility with the Cloudflare Workers ecosystem, enabling seamless local development and deployment, and its foundation on the proven, high-performance Cloudflare infrastructure. Unlike traditional Node.js runtimes, `workerd` is designed for a secure, isolated, and highly concurrent serverless model, with built-in support for web standards like `fetch` and `Durable Objects`.","status":"active","version":"1.20260421.1","language":"javascript","source_language":"en","source_url":"https://github.com/cloudflare/workerd","tags":["javascript"],"install":[{"cmd":"npm install workerd","lang":"bash","label":"npm"},{"cmd":"yarn add workerd","lang":"bash","label":"yarn"},{"cmd":"pnpm add workerd","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"`workerd` is often managed and invoked via Node.js tooling (e.g., `npx`, `wrangler`), and its `package.json` specifies Node.js `>=16` as a compatible engine. While the runtime itself is a C++ executable, its distribution and ecosystem heavily rely on Node.js.","package":"node","optional":true}],"imports":[{"note":"`workerd` ships ambient type definitions (`workerd.d.ts`) that declare global types like `Request`, `Response`, `DurableObjectState`, and `Env` for worker scripts. These types are typically made available via TypeScript configuration (`tsconfig.json`'s `types` array) or reference directives in source files, rather than direct `import` statements in worker code.","symbol":"(Global types for Workers environment)","correct":"/// <reference types=\"workerd\" />"},{"note":"The `unsafe` API, which provides advanced operations such as `deleteAllDurableObjects()`, is exposed as a property of the `workerd` namespace object. It is not a top-level named export. Use with extreme caution as these APIs bypass standard safety mechanisms.","wrong":"import { unsafe } from 'workerd';","symbol":"workerd.unsafe","correct":"import { workerd } from 'workerd';\nconst { unsafe } = workerd;"},{"note":"The `workerd` package exports a namespace object. For importing its type definitions (e.g., for configuration schemas or specific utility types), `import type` is preferred to ensure it's a type-only import, avoiding potential runtime overhead if `workerd` were to have a substantial runtime object.","wrong":"import { workerd } from 'workerd';","symbol":"workerd","correct":"import type { workerd } from 'workerd';"}],"quickstart":{"code":"/*\n1. Create your worker script: worker.js\n   Save this content to a file named `worker.js` in your project directory.\n*/\nexport default {\n  async fetch(request) {\n    const url = new URL(request.url);\n    if (url.pathname === '/greet') {\n      const name = url.searchParams.get('name') || 'World';\n      return new Response(`Hello, ${name} from workerd!`, {\n        headers: { 'Content-Type': 'text/plain' },\n        status: 200\n      });\n    }\n    return new Response('Not Found. Try visiting /greet?name=Alice', { status: 404 });\n  }\n};\n\n/*\n2. Create your workerd configuration file: workerd.capnp\n   This file tells the `workerd` runtime how to load and serve your worker.\n   Save this content to a file named `workerd.capnp` in the same directory.\n*/\n// using Workerd = /capnp/workerd.capnp;\n//\n// const config :Workerd.Config = (\n//   services = [\n//     (name = \"main\", worker = .worker),\n//   ],\n//   bundles = [\n//     (name = \"my-worker-bundle\", content = embed \"worker.js\"), // Reference your `worker.js` file\n//   ],\n//   sockets = [\n//     (name = \"http\", address = \"0.0.0.0:8080\", service = \"main\"), // workerd listens on port 8080\n//   ]\n// );\n//\n// const worker :Workerd.Worker = (\n//   serviceWorkerScript = .myWorkerBundle,\n//   compatibilityDate = \"2023-01-01\", // Required by Cloudflare Workers for consistent behavior\n//   compatibilityFlags = [\"nodejs_compat\"], // Example: Enable Node.js compatibility features\n// );\n\n/*\n3. Install workerd and run your worker\n   First, ensure you have Node.js and npm/npx installed.\n   Then, in your terminal, navigate to your project directory and run:\n\n   npm install workerd\n   npx workerd serve workerd.capnp\n\n   After running, open your web browser and visit:\n   - http://localhost:8080/greet             (Expected: \"Hello, World from workerd!\")\n   - http://localhost:8080/greet?name=Alice (Expected: \"Hello, Alice from workerd!\")\n*/","lang":"javascript","description":"This quickstart demonstrates how to set up and run a simple Cloudflare Worker locally using the `workerd` runtime, involving a JavaScript worker script and a Cap'n Proto configuration file."},"warnings":[{"fix":"Update `minBytes` to `minElements` when working with `ByobBuffer` instances.","message":"The `ByobBuffer` API has undergone a renaming of its `minBytes` property to `minElements`. Code interacting with `ByobBuffer` for BYOB (Bring-Your-Own-Buffer) streams will need to update to use the new property name.","severity":"breaking","affected_versions":">=1.20260421.1"},{"fix":"Migrate Durable Object replication logic to use the new `configureReadReplication()` method for future compatibility and improved control.","message":"APIs for Durable Object replication, `ensureReplicas()` and `disableReplicas()`, have been deprecated. They are replaced by a new, more flexible `configureReadReplication()` API.","severity":"deprecated","affected_versions":">=1.20260418.1"},{"fix":"Carefully review the Cap'n Proto syntax and `workerd`'s configuration schema documentation. Use a linter or IDE extension for Cap'n Proto if available. Refer to examples in the `workerd` GitHub repository.","message":"`workerd` uses Cap'n Proto (`.capnp` files) for its configuration. This is a powerful, schema-driven serialization format but can be unfamiliar to developers primarily working with JSON or YAML. Incorrect syntax or schema violations in `.capnp` files will prevent `workerd` from starting.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Regularly update your `workerd` installation (`npm update workerd`) and review the GitHub changelog for breaking changes or important behavior modifications, especially before upgrading in production-like environments.","message":"The `workerd` package follows a rapid, daily release cadence (e.g., `v1.YYYYMMDD.X`). While this ensures quick bug fixes and feature rollouts, it means local installations can become outdated very quickly, and specific behaviors or APIs might evolve rapidly between minor daily versions. This necessitates frequent updates and awareness of changelogs.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Verify the syntax of your `workerd.capnp` file. Ensure `using` and `const` statements are correctly formed and that there are no misplaced characters or incorrect indentation.","cause":"The Cap'n Proto configuration file (`.capnp`) has a syntax error or is malformed, preventing `workerd` from parsing its configuration.","error":"Error: workerd.capnp:1:0: Parse error: Expected 'using' or 'const' after top-level statement."},{"fix":"Check that the `name` field in your `bundles` array matches the `serviceWorkerScript` reference in your `worker` definition within `workerd.capnp`. Also, ensure the `content = embed \"worker.js\"` path correctly points to your worker script.","cause":"The worker configuration within `workerd.capnp` refers to a bundle name that is not defined in the `bundles` list, or the path to the worker script embedded in the bundle is incorrect.","error":"Error: Bundle 'my-worker-bundle' not found. This bundle must be defined in the bundles list."},{"fix":"Review your `worker.js` (or `worker.ts`) file for syntax errors or logical issues. Ensure all used APIs (like `fetch`) are correctly called within the Worker environment's context (e.g., within the `fetch` handler) and are supported by `workerd` or enabled by `compatibilityFlags`.","cause":"This error typically indicates that the worker script contains invalid JavaScript syntax, a runtime error, or attempts to access APIs not available in the `workerd` environment or within the worker's current scope.","error":"Error: Service 'main' failed to start: Error: worker initialization failed: TypeError: fetch is not a function"}],"ecosystem":"npm"}