Run Vite and Next.js
Use this guide when a web app runs on a Vite or Next.js dev server and each lane should serve its own copy under the lane’s hostname.
::example{slug="web-next-app"}
Add the preset
Section titled “Add the preset”A preset is the part of devlanes that knows a framework’s flags: it passes the lane’s port to the dev server and binds it to 127.0.0.1. Name it on the service, next to the script that starts the dev server:
Vite
services: web: preset: vite run_script: file: web/package.json name: dev hosts: "${{ lane.domain }}"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.
Next.js
services: web: preset: next run_script: file: web/package.json name: dev hosts: "${{ lane.domain }}" ready: http: path: / timeout: 120sservicesLong-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>.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.
services.<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.
services.<name>.ready.http.pathPath requested with GET, such as /healthz; defaults to /.
services.<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.
next dev compiles a page on its first request, so the ready check waits longer than the default.
The preset adds its flags at the end of the script, so the script’s last command has to be the dev server itself, as in "dev": "vite" or "dev": "next dev". In a Taskfile, end that command with {{.CLI_ARGS}}, as in dev: vite {{.CLI_ARGS}}.
Start the lane
Section titled “Start the lane”$ devlanes startThe start lists the web app on the lane’s hostname, such as https://myapp.localhost. With Vite, hot reload works through the proxy.
If lane domains use another top-level domain
Section titled “If lane domains use another top-level domain”Both dev servers accept localhost names without a setting. With another domain set through hostnames.tld, list it in server.allowedHosts for Vite, such as [".test"], or in allowedDevOrigins for Next.js, such as ["**.test"].
If the dev server proxies API calls
Section titled “If the dev server proxies API calls”Point the proxy at ${{ services.api.url }}, the API’s own port, rather than at its hostname. A proxy that sends a lane hostname back to devlanes reaches the same service again and gets DL104 Proxy loop.