wrangler dev: Usage & Common CI Errors
Run your Cloudflare Worker locally for development and testing.
wrangler dev starts a local server that runs your Worker against the Workers runtime (workerd), with hot reload. It is a long-running process - fine for dev, a trap for CI if you do not background it.
What it does
wrangler dev compiles your Worker and serves it locally (default on 127.0.0.1:8787) using the real Workers runtime, emulating bindings. By default it runs in local mode; --remote runs against Cloudflare’s edge. It stays in the foreground until interrupted.
Common usage
# Start the local dev server
wrangler dev
# Bind to a specific port
wrangler dev --port 8788
# Run against the real edge instead of local
wrangler dev --remoteCommon error in CI: dev server blocks the job forever
In CI, wrangler dev never exits - it is a server - so the job hangs until it times out. Fix: do not run a bare wrangler dev in a foreground CI step. Start it in the background, wait for the port, run your tests against http://127.0.0.1:8787, then kill it; or use a test runner with Miniflare/unstable_dev that starts and stops the Worker programmatically. For deploy, use wrangler deploy, not dev.
Key options
| Option | Purpose |
|---|---|
| --port N | Local port to listen on |
| --local / --remote | Local runtime vs the edge |
| --env NAME | Use a named environment |
| --var KEY=VAL | Override a variable |