Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
(Global types for Workers environment)
✓ /// <reference types="workerd" />
`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.
workerd.unsafe
✓ import { workerd } from 'workerd';
const { unsafe } = workerd;
✗ import { unsafe } from 'workerd';
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.
workerd
✓ import type { workerd } from 'workerd';
✗ import { workerd } from 'workerd';
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.
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.
/*
1. Create your worker script: worker.js
Save this content to a file named `worker.js` in your project directory.
*/
export default {
async fetch(request) {
const url = new URL(request.url);
if (url.pathname === '/greet') {
const name = url.searchParams.get('name') || 'World';
return new Response(`Hello, ${name} from workerd!`, {
headers: { 'Content-Type': 'text/plain' },
status: 200
});
}
return new Response('Not Found. Try visiting /greet?name=Alice', { status: 404 });
}
};
/*
2. Create your workerd configuration file: workerd.capnp
This file tells the `workerd` runtime how to load and serve your worker.
Save this content to a file named `workerd.capnp` in the same directory.
*/
// using Workerd = /capnp/workerd.capnp;
//
// const config :Workerd.Config = (
// services = [
// (name = "main", worker = .worker),
// ],
// bundles = [
// (name = "my-worker-bundle", content = embed "worker.js"), // Reference your `worker.js` file
// ],
// sockets = [
// (name = "http", address = "0.0.0.0:8080", service = "main"), // workerd listens on port 8080
// ]
// );
//
// const worker :Workerd.Worker = (
// serviceWorkerScript = .myWorkerBundle,
// compatibilityDate = "2023-01-01", // Required by Cloudflare Workers for consistent behavior
// compatibilityFlags = ["nodejs_compat"], // Example: Enable Node.js compatibility features
// );
/*
3. Install workerd and run your worker
First, ensure you have Node.js and npm/npx installed.
Then, in your terminal, navigate to your project directory and run:
npm install workerd
npx workerd serve workerd.capnp
After running, open your web browser and visit:
- http://localhost:8080/greet (Expected: "Hello, World from workerd!")
- http://localhost:8080/greet?name=Alice (Expected: "Hello, Alice from workerd!")
*/
workerd --version
Errors
Common errors & fixes
Error: workerd.capnp:1:0: Parse error: Expected 'using' or 'const' after top-level statement.
The Cap'n Proto configuration file (`.capnp`) has a syntax error or is malformed, preventing `workerd` from parsing its configuration.
fixVerify 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.
Error: Bundle 'my-worker-bundle' not found. This bundle must be defined in the bundles list.
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.
fixCheck 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.
Error: Service 'main' failed to start: Error: worker initialization failed: TypeError: fetch is not a function
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.
fixReview 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`.
Upgrade
Version history
1.20260421.1latest on npm
Audit
Dependencies
nodeoptional`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.