Frontend and API on one lane domain
A React page served by Vite and a Hono API, each on its own HTTPS hostname under the lane’s domain. The page calls the API with CORS and a session cookie set on the lane domain.
Requirements
Section titled “Requirements”- devlanes, with
devlanes setuprun once - Node 22.12 or later
Run it
Section titled “Run it”cd web-frontend-apidevlanes startdevlanes start --no-ui prints the start as text:
example-frontend-api@0 (main): 2/2 readyready api http://127.0.0.1:20580 https://api.example-frontend-api.localhostready web http://127.0.0.1:20581 https://example-frontend-api.localhostOpen https://example-frontend-api.localhost. The page says This is lane 0 of example-frontend-api. and shows the items it fetched from https://api.example-frontend-api.localhost, the same API reached through /proxied on the page’s own host, and a Sign in button.
During a start
Section titled “During a start”- The first start of a lane runs the
installtask: onenpm installat the example root installs both workspaces,apps/apiandapps/web. apirunstsx watch src/index.tson itsPORTand counts as ready once/healthzanswers. It serves https://api.example-frontend-api.localhost.webrunsvitewith the flagspreset: viteadds (--port <port> --strictPort --host 127.0.0.1) and serves https://example-frontend-api.localhost. Vite accepts.localhosthostnames withoutserver.allowedHosts, and HMR reaches the page through the devlanes proxy without anyserver.hmrsettings.
url and public_url
Section titled “url and public_url”web gets the API’s address twice:
VITE_API_URL: ${{ services.api.public_url }}ishttps://api.example-frontend-api.localhost. Vite putsVITE_*variables into the code it sends to the browser, so this value has to be the hostname: requests to it go through the devlanes proxy, get HTTPS and belong to the lane’s site.API_PROXY_TARGET: ${{ services.api.url }}ishttp://127.0.0.1:<port>. Only Vite’sserver.proxyon this machine uses it, so it skips TLS and the proxy hop.https://example-frontend-api.localhost/proxied/lanegoes from the browser to Vite to the API without leaving the page’s origin, so it needs no CORS.
devlanes env show web | grep -E "API_URL|API_PROXY|ORIGINS"API_PROXY_TARGET=http://127.0.0.1:20580DEVLANES_ORIGINS=https://api.example-frontend-api.localhost,http://localhost:20580,http://127.0.0.1:20580,https://example-frontend-api.localhost,http://localhost:20581,http://127.0.0.1:20581VITE_API_URL=https://api.example-frontend-api.localhostCookies and CORS between the hostnames
Section titled “Cookies and CORS between the hostnames”example-frontend-api.localhost and api.example-frontend-api.localhost are two origins on one site, example-frontend-api.localhost.
The page’s fetch to the API is cross-origin, so the browser reads the answer only when it carries CORS headers. The API sends Access-Control-Allow-Origin only to origins listed in DEVLANES_ORIGINS, which devlanes sets on every service to the lane’s https origins plus http://localhost:<port> and http://127.0.0.1:<port> for each service. Access-Control-Allow-Credentials: true lets the browser send and store the cookie on those requests.
POST /api/session sets session=...; Domain=example-frontend-api.localhost; Path=/; Secure; SameSite=Lax, with the domain from COOKIE_DOMAIN: ${{ lane.domain }}. The cookie reaches both hostnames, and requests between them are same-site, so SameSite=Lax lets it through. The page shows it in document.cookie and reads it back with GET /api/me. Lane 1’s domain is example-frontend-api1.localhost, which is another site.
Try next
Section titled “Try next”Start a second lane:
git worktree add ../examples-checkout -b feat/checkout, thencd ../examples-checkout/web-frontend-api && devlanes start. To stay in this folder instead, rundevlanes lane new --name review --start. https://example-frontend-api1.localhost showsThis is lane 1 of example-frontend-api.and loads its items from https://api.example-frontend-api1.localhost.Click Sign in on https://example-frontend-api.localhost, then open https://example-frontend-api1.localhost. Lane 1 shows
document.cookieas(empty)andnot signed in, becauseexample-frontend-api1.localhostis not underexample-frontend-api.localhost.Sign in and Sign out on lane 1 set and clear a cookie of its own, and lane 0 stays signed in.
Point lane 1’s page at lane 0’s API with https://example-frontend-api1.localhost/?api=https://api.example-frontend-api.localhost. The cross-origin and cookie cards show
Failed to fetch, and the browser console says:Access to fetch at 'https://api.example-frontend-api.localhost/api/items' from origin 'https://example-frontend-api1.localhost' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource.Lane 0’s
DEVLANES_ORIGINSlists only lane 0’s origins. The headers show it (on Windows, add--ssl-revoke-best-efforttocurl):Terminal window curl -sS -D - -o /dev/null -H "Origin: https://example-frontend-api1.localhost" https://api.example-frontend-api.localhost/api/itemsHTTP/1.1 200 OKaccess-control-allow-credentials: truecontent-type: application/jsonvary: Origincontent-length: 216date: Sat, 07 Nov 2026 01:01:35 GMTvia: 1.1 devlanes.runWith
Origin: https://example-frontend-api.localhostthe same request also getsaccess-control-allow-origin: https://example-frontend-api.localhost.Edit the heading in
apps/web/src/App.tsxand save. The page updates without reloading, and the browser console logs[vite] hot updated: /src/App.tsx.devlanes lane clean 0 --yesstops lane 0 and deletes its data and logs. Run it withreviewfor the lane fromlane new, or with1from the second worktree.
devlanes.yaml: theinstalltask,apiwith its hostname andCOOKIE_DOMAIN,webwithpreset: viteand both API addresses.apps/api/src/: the Hono API.app.tsmounts the routes,cors.tsbuilds the allow-list fromDEVLANES_ORIGINS,routes/session.tssets the cookie.apps/web/vite.config.ts: the/proxiedroute toAPI_PROXY_TARGET.apps/web/src/: the page.api.tsmakes the calls.