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
Build workerd
First, build workerd from source: bazel build //src/workerd/server:workerd
The binary will be at bazel-bin/src/workerd/server/workerd.
Install Wrangler
You need Wrangler v3.0 or greater: 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:
Linux/macOS
Using repository path
Windows
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:
Start dev server
With specific port
With remote mode
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
Make changes
Edit workerd source code as needed.
Rebuild workerd
bazel build //src/workerd/server:workerd
Or use Just:
Restart Wrangler
Stop the current wrangler dev session and restart it: Wrangler will pick up the newly built binary. Example: Testing a Worker Create a simple Worker project:
Create project
mkdir my-worker && cd my-worker npm init -y npm install wrangler --save-dev
Create Worker script
Create src/index.js: export default { async fetch ( request , env , ctx ) { return new Response ( 'Hello from local workerd!' ); } , } ;
Configure Wrangler
Create wrangler.toml: name = "my-worker" main = "src/index.js" compatibility_date = "2024-01-01"
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:
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:
Verbose logging
Inspect mode
Local mode
wrangler dev --log-level debug
When using --inspect, you can connect Chrome DevTools at chrome://inspect.
Troubleshooting
Wrangler not using local workerd
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
Version mismatch warnings
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