Dotenv and one domain root
Two Hono services, web at https://example-dotenv.localhost and api at https://api.example-dotenv.localhost, read a gitignored .env that holds an API token, feature flags and an optional Sentry DSN. They build every URL and their cookie domain from APP_DOMAIN: ${{ lane.domain }}, so lanes share one .env and still get their own URLs.
Requirements
Section titled “Requirements”- devlanes, with
devlanes setuprun once - Node 22 or later
Run it
Section titled “Run it”cd workflows-dotenvcp .env.example .envdevlanes startWithout .env, both services fail on ACME_API_TOKEN, the one key devlanes.yaml requires, with devlanes.yaml in global_env.ACME_API_TOKEN is invalid: expression resolved to an undefined value and the file and line.
devlanes start --no-ui prints the start as text:
example-dotenv@0 (main): 2/2 readyready web http://127.0.0.1:20531 https://example-dotenv.localhostready api http://127.0.0.1:20530 https://api.example-dotenv.localhostOpen https://example-dotenv.localhost. The page lists every key in .env with what reached the web process: ACME_API_TOKEN is set with its value hidden, FEATURE_FLAGS shows new-checkout,dark-mode, SENTRY_DSN is empty, and ACME_ADMIN_PASSWORD is not in this process.
During a start
Section titled “During a start”- devlanes evaluates
global_envfor the lane. It reads.envonly for${{ env.X }}expressions, soglobal_envnames each key a process gets.${{ env.X }}looks in the shell that ran devlanes first, then in.env.ACME_API_TOKENhas no default, so the start fails without it.FEATURE_FLAGSandSENTRY_DSNuse| default('')and come out empty instead. - The first start of a lane runs the
installtask (npm installat the example root). webandapistart withPORT,HOSTand the sameglobal_env. From.envthey get the three keysglobal_envnames and nothing else.- The ready checks wait for
/healthz. The proxy routesexample-dotenv.localhostandassets.example-dotenv.localhosttowebandapi.example-dotenv.localhosttoapi.
One domain root
Section titled “One domain root”Each app’s src/env.ts passes APP_DOMAIN to appUrls in packages/config, which derives the web, api and asset URLs and the cookie domain. The page loads its CSS and logo from https://assets.example-dotenv.localhost and sets an acme_session cookie with Domain=example-dotenv.localhost. On the server, web calls https://api.example-dotenv.localhost/api/orders with ACME_API_TOKEN as a bearer token, and api checks it against its own copy from the same .env (200, 3 orders). In the browser, the page calls /api/session on the api with the cookie and shows api saw acme_session=.... The api allows the origin because it is in DEVLANES_ORIGINS.
To list the keys, web reads the same .env that devlanes reads, takes only the names, and looks each one up in its own environment. dotenvSummary in packages/config hides the values of keys named like secrets. In this repository the project file sits in a subfolder: devlanes reads .env next to devlanes.yaml, while ${{ lane.path }} and ${{ project.primary_path }} are the repository root. web joins DOTENV_ROOT with the example’s path inside the worktree to find the primary worktree’s copy.
Try next
Section titled “Try next”In
.env, changeFEATURE_FLAGStonew-checkout,dark-mode,beta-searchand save. The running services keep the old value, anddevlanes statusnames the variable without its value:example-dotenvLANE BRANCH STATE SERVICES CPU MEM URL0 main running 2/2 0.0% 179.3 MiB https://example-dotenv.localhost (config changed: 2 changed; devlanes reload --lane example-dotenv@0 applies it)UNIT STATE PORT CPU MEM URLweb ready 20531 0.0% 91.9 MiB https://example-dotenv.localhostapi ready 20530 0.0% 87.5 MiB https://api.example-dotenv.localhostinstall exited – – –web: env FEATURE_FLAGS changed in the project fileapi: env FEATURE_FLAGS changed in the project filedevlanes reloadrestarts both services. The page and https://api.example-dotenv.localhost then listbeta-search.Change
ACME_ADMIN_PASSWORDin.env.devlanes statusshows no change, since no expression reads that key.Set
SENTRY_DSN=https://public@sentry.example.invalid/1in.env.devlanes statuslistsenv SENTRY_DSNfor both services.devlanes reload webrestarts onlyweb, whose page then showsSENTRY_DSNassetandSentryason, whileapistays marked until a plaindevlanes reload.The shell comes before
.env:FEATURE_FLAGS=from-shell devlanes restart api, and https://api.example-dotenv.localhost lists onlyfrom-shell.devlanes restart apifrom a shell without the variable goes back to the value in.env.Edit
packages/config/src/urls.tsand save. Both apps load it from source, sodevlanes logs apishows[tsx] change in ./..\..\packages\config\src\urls.ts Restarting...(with/on macOS and Linux), andwebrestarts the same way.Start a second lane in a new worktree:
git worktree add ../examples-checkout -b feat/checkout, thencd ../examples-checkout/workflows-dotenv && devlanes start. The new worktree has no.env, since Git does not copy ignored files.${{ env.X }}then falls back to the primary worktree’s.env, and the page’sfilerow names that file. Lane 1 answers at https://example-dotenv1.localhost withAPP_DOMAINset toexample-dotenv1.localhost.For a second lane without a worktree,
devlanes lane new --name example-dotenv-review --startadds lane 1 in this folder. Its page at https://example-dotenv1.localhost showsAPP_DOMAINexample-dotenv1.localhost, the api at https://api.example-dotenv1.localhost and a cookie withDomain=example-dotenv1.localhost. Both lanes read the same.env, so an edit marks both:example-dotenvLANE BRANCH STATE SERVICES CPU MEM URL0 main running 2/2 0.0% 136.5 MiB https://example-dotenv.localhost (config changed: 2 changed; devlanes reload --lane example-dotenv@0 applies it)1 main running 2/2 0.0% 136.8 MiB https://example-dotenv1.localhost (config changed: 2 changed; devlanes reload --lane example-dotenv@1 applies it)devlanes reloadapplies lane 0 anddevlanes reload --lane example-dotenv-reviewlane 1.When you are done,
devlanes lane clean example-dotenv-review --yesanddevlanes lane clean 0 --yesstop the lanes and delete their data.
.env.example: the fake values to copy to.env, includingACME_ADMIN_PASSWORD, which no process gets.devlanes.yaml:global_envwithAPP_DOMAIN,DOTENV_ROOTand the${{ env.X }}keys, theinstalltask, and thewebandapiservices.packages/config/src/:urls.tsbuilds every URL and the cookie domain fromAPP_DOMAIN, anddotenv.tsfinds.envand summarizes its keys with secrets hidden.apps/web/src/: the web routes, theacme_sessioncookie and the server-side call to the api.apps/api/src/:/api/ordersbehind the token and/api/sessionwith CORS fromDEVLANES_ORIGINS.