Services that find each other
You add a web app to myapp: a page served by Vite that asks the API which lane it belongs to. Each lane serves the page, and each page has to call the API of its own lane, so no URL written into the code can be right for both.
The web app takes the lane’s domain
Section titled “The web app takes the lane’s domain”On the main branch you add the web service and a task that installs the packages. Where the web app needs the API’s URL, the file holds an expression that reads the API’s public URL; like the one in each hostname, devlanes works it out for each lane before the service starts.
tasks: install: run: [npm, install] when: lane.create
services: web: preset: vite run_script: file: web/package.json name: dev hosts: "${{ lane.domain }}" env: VITE_API_URL: "${{ services.api.public_url }}"tasksOne-shot commands such as installs, migrations and seeds, run by hand with devlanes run <name> or automatically at a lane event set with when. Tasks of the same event run in declaration order.
tasks.<name>A one-shot command, run by hand with devlanes run <name> or automatically at a lane event set with when. Anything that ends by itself belongs here, not in services, where an exit counts as a failure.
tasks.<name>.runCommand to run: a string runs through /bin/sh -c (pipes and multi-line scripts work), a list runs the program directly with those arguments. Use exactly one of run, run_script or steps. In a list, an item that is one ${{ }} expression giving a number or true/false becomes its text, such as --port followed by ${{ self.port }}.
tasks.<name>.whenLane event that runs this task automatically. Without it the task runs only by hand with devlanes run <name> or as a step of another task.
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>.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] }.
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>.envEnvironment variables for this service's process. They override global_env and are overridden by the active profile's env and --env; values may be text, numbers, booleans or ${{ ... }} expressions. Setting PORT replaces the port devlanes allocated; a literal number is the same in every lane, so lanes collide.
services.<name>.env.<name>Environment variables for this service's process. They override global_env and are overridden by the active profile's env and --env; values may be text, numbers, booleans or ${{ ... }} expressions. Setting PORT replaces the port devlanes allocated; a literal number is the same in every lane, so lanes collide.
The web service takes the lane’s domain itself as its hostname, which had nothing on it until now. Vite takes its port as a flag and ignores PORT, so the web service names a preset, a set of flags and settings devlanes adds for a dev server it knows; the vite preset passes the lane’s port, the loopback address and a flag that makes Vite exit when that port is taken.
Starting a stopped lane runs its tasks
Section titled “Starting a stopped lane runs its tasks”Both lanes are stopped. You merge main into the checkout branch and start each lane.
$ devlanes start --no-ui$ devlanes start --no-uiEach start runs the install, then the API and the web app, whose page is at https://myapp.localhost in lane 0 and https://myapp1.localhost in lane 1. The install is a task, a unit that runs a command and ends. As a lane.create task it runs at each start of a stopped lane until it has succeeded once in that lane. A start into a running lane adds the services it lacks and runs no tasks, so you stop a lane before a start that has to run them.
Each lane hands the web app its own API
Section titled “Each lane hands the web app its own API”$ devlanes env show webIn lane 1 the web app gets VITE_API_URL=https://api.myapp1.localhost, the URL a browser uses, through the proxy. A call from another service of the lane would use services.api.url instead, the API’s port on the loopback address.
The API answers the page of its own lane
Section titled “The API answers the page of its own lane”Vite passes variables whose names start with VITE_ to the page code, so the page fetches the URL its lane gives it. The page and the API have different hostnames, so the browser reads the API’s answer only if the API allows the page’s origin. devlanes gives every service of a lane the lane’s origins in DEVLANES_ORIGINS, and the API checks each request against it.
const apiUrl = import.meta.env.VITE_API_URL;const el = document.getElementById("lane");
fetch(apiUrl) .then((res) => res.json()) .then((body) => { el.textContent = `The API at ${apiUrl} answers from lane ${body.lane} (${body.lane_name}).`; });
// api/server.mjsconst origins = (process.env.DEVLANES_ORIGINS ?? "").split(",").filter(Boolean);
const server = createServer((req, res) => { const origin = req.headers.origin; if (origin && origins.includes(origin)) { res.setHeader("access-control-allow-origin", origin); }The API of lane 1 allows the page of lane 1 and sends no such header to the page of lane 0.
The API is about to keep data in Postgres, and A database for each lane gives each lane a database of its own.