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"}
Add the Workers
Section titled “Add the 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:
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 }}"templatesNamed service settings that services reuse with extends: <template>. The service inherits every setting of the template and its own settings win: mappings (env, ready, stop, preset options, run_script) merge by key, lists (tags, hosts, sync) and single values replace. Setting run or run_script drops the inherited other one, and one ready probe (tcp, http, log, cmd) drops the inherited probe. Templates may extend other templates, are never started themselves, and are applied after every project file and local override is merged.
templates.<name>A long-running process started with the lane, such as a dev server or a worker. Each service gets its own port from the lane's block (PORT, ${{ self.port }}); devlanes stops it with the lane and never restarts it when it exits. A service needs run or run_script, directly or through extends.
templates.<name>.presetFramework integration that adds the flags and variables a dev server needs to run in a lane, such as --port <port> --strictPort --host 127.0.0.1 for vite or SERVER_PORT for spring-boot, so you do not pass them yourself. One of vite, next, wrangler, tauri, spring-boot or quarkus. Requires run_script (quarkus needs a pom.xml or build.gradle(.kts) one); with a hand-written run, drop the preset and pass its flags yourself. Its options go under a sibling key with the preset's name, for example vite: { args: [--open] }.
templates.<name>.readyWhen the service counts as up: once its check passed and it has run half a second. devlanes start waits for it, and after: services tasks run once every started service is ready. Write started (no probe) or a mapping with one of tcp, http, log or cmd, plus timeout (default 60s). Without it, a service with hosts waits for TCP on its port and one without hosts uses started. A service that exits within that half second failed to start. A check that times out marks the service failed, which also skips after: services tasks; the process keeps running and is not restarted.
templates.<name>.ready.httpReady once a GET request to path on the unit's main port answers with status, or with a 2xx status when status is unset. Redirects are not followed. Best when the app has a health route that fails while it is broken. Each request sends User-Agent: devlanes-ready, so an app can leave the checks out of its request logs.
templates.<name>.ready.http.pathPath requested with GET, such as /healthz; defaults to /.
templates.<name>.ready.http.timeoutHow long the HTTP check may take to pass, replacing the check's timeout; defaults to 60s. When it runs out, a service is marked failed but keeps running, and for an infra container the start fails.
templates.<name>.wranglerOptions for preset: wrangler, which gives each lane's wrangler dev its own --port <self.port>, --inspector-port <self.ports.inspector> and dev registry. The inspector port is allocated automatically. args that pass either port flag are refused by devlanes config check, and a run_script script that does is refused at start.
templates.<name>.wrangler.argsExtra arguments for wrangler dev, added after the port and --var flags, for example [--env-file, .dev.vars]. --port and --inspector-port (or --inspectorPort) are refused here, since the preset already sets them per lane. A local override or extends child that sets args replaces the inherited list.
servicesLong-running processes of each lane, started together after infrastructure, setup and lane.start tasks. Each service gets its own port as PORT and, with hosts, HTTPS hostnames. A service that exits shows as failed and is not restarted.
services.<name>A long-running process started with the lane, such as a dev server or a worker. Each service gets its own port from the lane's block (PORT, ${{ self.port }}); devlanes stops it with the lane and never restarts it when it exits. A service needs run or run_script, directly or through extends.
services.<name>.extendsTemplate under templates whose settings this service inherits; its own settings apply on top. Mappings (env, ready, stop, preset options, run_script) merge by key, lists (tags, hosts, sync) and single values replace. Setting run or run_script drops the inherited other one, and one ready probe (tcp, http, log, cmd) drops the inherited probe. Templates may extend other templates and are resolved after every project file and local override is merged.
services.<name>.run_scriptScript to run from a project file, as { file, name }, such as { file: apps/api/package.json, name: dev }. devlanes picks the tool from the file name (package.json, Makefile, justfile, Taskfile.yml, deno.json, pyproject.toml, Cargo.toml, go.mod, pom.xml, build.gradle(.kts), settings.gradle(.kts)), runs the script in that file's directory and checks that it exists before starting. For Maven and Gradle, name is the arguments as typed after mvn or gradle, and Maven or Gradle reports a goal or task that does not exist. Presets need it to place their flags, and a profile's run_scripts can swap the script name. Exactly one of run and run_script is required after templates are applied.
services.<name>.run_script.fileFile that defines the script, relative to the project file's directory, such as apps/api/package.json. The script runs in this file's directory. Required unless an override or extends child keeps the inherited file.
services.<name>.run_script.nameScript, target, recipe, task, binary or package name in that file. For go.mod, a bare name such as api means ./cmd/api, and . or a path with / is relative to go.mod. For pom.xml and Gradle files it is the arguments as typed after mvn or gradle, such as -pl web -am spring-boot:run or :web:bootRun; quote an argument that contains spaces, as in a shell. It must name at least one goal or task. Required unless an override or extends child keeps the inherited name.
services.<name>.hostsHostnames the devlanes HTTPS proxy routes to this service, so https://<host> reaches it. One entry or a list; an entry is a hostname or a mapping with host and optional port (a named port), fallback and host_header. A *. wildcard matches subdomains, and an exact host wins over it. The first non-wildcard host becomes public_url, non-wildcard hosts join the lane's DEVLANES_ORIGINS, and having hosts makes the default ready a TCP check. Keep them under ${{ lane.domain }} so lanes do not collide.
services.<name>.hosts[].hostHostname to route, evaluated for each lane. A leading *. makes a wildcard that matches any depth below it but not the name itself; quote it in YAML. Labels hold letters, digits and inner hyphens; case and a trailing dot are ignored.
services.<name>.hosts[].portSend this hostname to one of the unit's named ports instead of its main port. For a service it is a port name as in self.ports.<name>, and naming it here allocates that port; in infra.hosts it is the container port for Compose services, or the port's name for plain containers.
services.<name>.hosts[].host_headerHost header the unit receives. Defaults to preserve, the hostname the browser asked for; upstream sends the local address, such as 127.0.0.1:<port>, for servers that reject or misroute requests for a Host that is not their own address.
services.<name>.wranglerOptions for preset: wrangler, which gives each lane's wrangler dev its own --port <self.port>, --inspector-port <self.ports.inspector> and dev registry. The inspector port is allocated automatically. args that pass either port flag are refused by devlanes config check, and a run_script script that does is refused at start.
services.<name>.wrangler.varsWorker variables for this lane, each passed as --var KEY:VALUE so it overrides the same name in the Wrangler config's vars. Values can be strings, numbers or booleans (sent as text) and may use expressions such as ${{ self.public_url }}; names must be non-empty and cannot contain :. Local overrides and extends children merge with inherited vars per name.
services.<name>.wrangler.vars.<name>Worker variables for this lane, each passed as --var KEY:VALUE so it overrides the same name in the Wrangler config's vars. Values can be strings, numbers or booleans (sent as text) and may use expressions such as ${{ self.public_url }}; names must be non-empty and cannot contain :. Local overrides and extends children merge with inherited vars per name.
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.
Start the lane
Section titled “Start the lane”$ devlanes startThe 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.
If you use the Cloudflare Vite plugin
Section titled “If you use the Cloudflare Vite plugin”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.