Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/cloudflare/workerd/llms.txt

Use this file to discover all available pages before exploring further.

You can use a locally-built version of workerd with Wrangler for developing Cloudflare Workers.

​
Why use a local build?

Using a local workerd build with Wrangler allows you to:
  • Test new workerd features before they’re released
  • Debug workerd runtime issues
  • Contribute to workerd development
  • Validate fixes for runtime bugs

​
Prerequisites

1

Build workerd

First, build workerd from source:
bazel build //src/workerd/server:workerd
The binary will be at bazel-bin/src/workerd/server/workerd.
2

Install Wrangler

You need Wrangler v3.0 or greater:
npm install -g wrangler
Or use it from a project:
npm install --save-dev wrangler

​
Configuration

Set the MINIFLARE_WORKERD_PATH environment variable to point to your local workerd binary: 
export MINIFLARE_WORKERD_PATH="/path/to/workerd/bazel-bin/src/workerd/server/workerd"
Add this to your shell profile (.bashrc, .zshrc, etc.) to make it permanent.

​
Running Wrangler with local workerd

Once configured, use Wrangler commands normally: 
wrangler dev
Wrangler will now use your local workerd binary instead of the bundled one.

​
Verifying the setup

Check that Wrangler is using your local build: 
wrangler dev --log-level debug
You should see log output mentioning your local workerd path.

​
Development workflow

1

Make changes

Edit workerd source code as needed.
2

Rebuild workerd

bazel build //src/workerd/server:workerd
Or use Just:
just build
3

Restart Wrangler

Stop the current wrangler dev session and restart it:
wrangler dev
Wrangler will pick up the newly built binary.

​
Example: Testing a Worker

Create a simple Worker project:
1

Create project

mkdir my-worker && cd my-worker
npm init -y
npm install wrangler --save-dev
2

Create Worker script

Create src/index.js:
export default {
  async fetch(request, env, ctx) {
    return new Response('Hello from local workerd!');
  },
};
3

Configure Wrangler

Create wrangler.toml:
name = "my-worker"
main = "src/index.js"
compatibility_date = "2024-01-01"
4

Run with local workerd

export MINIFLARE_WORKERD_PATH="/path/to/workerd/bazel-bin/src/workerd/server/workerd"
npx wrangler dev
Visit http://localhost:8787 to see your Worker running on your local workerd build.

​
Testing compatibility flags

You can test new compatibility flags or features:
wrangler.toml
name = "my-worker"
main = "src/index.js"
compatibility_date = "2024-03-01"
compatibility_flags = ["nodejs_compat", "streams_enable_constructors"]
This allows you to validate that compatibility flags work as expected in your local workerd build.

​
Debugging with Wrangler

Combine Wrangler with workerd debugging features: 
wrangler dev --log-level debug
When using --inspect, you can connect Chrome DevTools at chrome://inspect.

​
Troubleshooting

Verify the environment variable is set:
echo $MINIFLARE_WORKERD_PATH
Ensure the path points to the correct binary (not a directory).
Make sure the workerd binary is executable:
chmod +x bazel-bin/src/workerd/server/workerd
If you see compatibility warnings, your local workerd may be significantly different from the version Wrangler expects. This is usually safe for development but may cause unexpected behavior.
Double-check that you’ve built workerd:
ls -la bazel-bin/src/workerd/server/workerd
If the file doesn’t exist, run:
bazel build //src/workerd/server:workerd

​
Using with watch mode

For active development, you can watch for changes and rebuild automatically: 
just watch build //src/workerd/server:workerd
In another terminal, run Wrangler and restart it whenever the build completes.

​
Advanced: Multiple workerd versions

You can maintain multiple workerd builds for different purposes: 
# Build release version
bazel build //src/workerd/server:workerd --config=release

# Build debug version
bazel build //src/workerd/server:workerd

# Switch between them
export MINIFLARE_WORKERD_PATH="$(pwd)/bazel-bin/src/workerd/server/workerd"

​
Running workerd directly

For cases where you don’t need Wrangler’s full features, you can run workerd directly: 
workerd serve config.capnp
See the configuration guide for details on creating workerd config files.

​
Next steps

Configuration

Learn about workerd configuration

Testing

Test your workerd changes

Build docs developers (and LLMs) love

Get started for freeTalk to us