Skip to content

devlanes is in beta and not ready for production use.Report an issue

Run Cloudflare Workers

Use this guide when a project runs Cloudflare Workers locally with Wrangler, and each lane needs its own Workers, bindings and stored data.

::example{slug="frameworks-wrangler-workers"}

The wrangler preset starts wrangler dev on the lane’s port, with a second named port for the inspector. Each lane gets its own Wrangler dev registry, so a service binding reaches the Worker of the same lane. A template holds what the Workers share:

devlanes.yaml
templates:
worker:
preset: wrangler
ready:
http:
path: /healthz
timeout: 180s
wrangler:
args: [--persist-to, "${{ lane.data_path }}/wrangler/${{ self.name }}"]
services:
gateway:
extends: worker
run_script:
file: apps/gateway/package.json
name: dev
hosts:
- "${{ lane.domain }}"
- host: "inspect-gateway.${{ lane.domain }}"
port: inspector
host_header: upstream
wrangler:
vars:
CATALOG_URL: "${{ services.catalog.public_url }}"
catalog:
extends: worker
run_script:
file: apps/catalog/package.json
name: dev
hosts: "catalog.${{ lane.domain }}"

Keep the dev script a plain wrangler dev, since the preset passes the ports itself. --persist-to keeps each lane’s KV, D1 and R2 data in the lane data folder, a folder only that lane uses. Here each Worker has a folder of its own. Workers that bind the same KV namespace, D1 database or R2 bucket see the same local data only through one folder, so for those leave ${{ self.name }} out of the path. A Worker does not see the process environment, so lane values reach it through services.<name>.wrangler.vars. The inspector hostname needs host_header: upstream, because the inspector accepts only its own address.

~/dev/myapp
$ devlanes start

The start lists each Worker on its hostname, and the inspector on inspect-gateway.myapp.localhost.

If a Worker fetches another by its hostname

Section titled “If a Worker fetches another by its hostname”

On macOS and Linux, workerd looks lane hostnames up in DNS, so set lanes.hosts_file to always and run devlanes setup once the lane has started. On Windows nothing is needed.

Use the vite preset from Run Vite and Next.js, set INSPECTOR_PORT: ${{ self.ports.inspector }} in the service’s env, and pass Number(process.env.INSPECTOR_PORT) to the plugin’s inspectorPort in vite.config.ts.