Builtin variables

Varlock provides a set of builtin VARLOCK_* variables that are automatically populated with information about the current CI/deploy platform, git branch, commit, and inferred deployment environment. They are entirely opt-in: they only exist in your schema when you reference them.

Usage

Builtin variables are activated when you reference them via $VARLOCK_* in a value expression:

# @currentEnv=$VARLOCK_ENV
# ---
BUILD_TAG="build-$VARLOCK_COMMIT_SHA_SHORT"
DB_URL=if(
  eq($VARLOCK_ENV, development),
  postgres://localhost/myapp,
  postgres://${VARLOCK_ENV}-db.example.com/myapp
)

If you want to include a builtin variable in your resolved env without referencing it from another item, define it with an empty value and varlock will populate it automatically:

VARLOCK_BRANCH=
VARLOCK_COMMIT_SHA_SHORT=

You can also use VARLOCK_ENV as your environment flag with @currentEnv, which means you don’t need to create your own APP_ENV variable. Varlock will auto-detect the environment for you.

Builtin Vars

`VARLOCK_ENV`

Type: string, one of development, preview, staging, production, test

The inferred deployment environment. Detection follows this priority:

Test environment: detected from NODE_ENV=test, VITEST, JEST_WORKER_ID, or VITEST_POOL_ID
Platform-provided: uses the platform’s own environment concept (e.g., Vercel’s VERCEL_ENV, Netlify’s CONTEXT)
Branch inference: in CI, infers from branch name: main/master/production/prod → production, staging/stage/develop/dev → staging, qa/test → test, anything else → preview
CI fallback: if in CI but no branch info is available, defaults to preview
Local fallback: if not in CI, defaults to development

Using with `@currentEnv`

# @currentEnv=$VARLOCK_ENV
# ---
DB_HOST=if(forEnv(production), "prod-db.example.com", "localhost")
DB_NAME=myapp
DB_URL="postgres://$DB_HOST/$DB_NAME"

If you already have your own flag and want to keep the name, derive its value from $VARLOCK_ENV instead of setting it yourself at runtime:

# @currentEnv=$APP_ENV
# ---
# @type=enum(development, preview, staging, production, test)
APP_ENV=$VARLOCK_ENV

An explicit APP_ENV=staging passed into the process still takes precedence, and test runs are detected without passing anything.

Your enum needs to cover every value $VARLOCK_ENV can produce. If your environments do not line up, use remap() to translate them. Unmatched values pass through unchanged, so you only list what differs:

# @currentEnv=$APP_ENV
# ---
# @type=enum(development, staging, production, test)
APP_ENV=remap($VARLOCK_ENV, preview, staging)

We do not recommend using NODE_ENV itself as your environment flag; see @currentEnv.

Test environment caveat

Test detection reads NODE_ENV=test, VITEST, VITEST_POOL_ID, and JEST_WORKER_ID. Which of those exist, and where, depends on your runner:

Runner	Signals available
Vitest, parent and workers	`VITEST` and `NODE_ENV=test` (workers also get `VITEST_POOL_ID`)
Jest, worker-scoped code (`setupFiles`, `setupFilesAfterEnv`, test files, app code under test)	`JEST_WORKER_ID` and `NODE_ENV=test`
Jest, parent-scoped code (`jest.config.*`, `globalSetup`)	`NODE_ENV=test` only
`bun test`, AVA	`NODE_ENV=test` only
`node --test`, Mocha	none

Both Vitest and Jest set their signals during their own startup, before config files are loaded, so importing varlock/auto-load from a config file, a setup file, or app code under test is late enough to see them. Verified against Vitest 4.1.5 and Jest 30.5.1; if you rely on this, confirm it for the runner and version you use.

Runners that set no signal. node --test and Mocha set nothing varlock can read, so VARLOCK_ENV never resolves to test under them.

An inherited NODE_ENV. Test runners set NODE_ENV=test only when it is unset, so a value already present in your shell or CI survives. Anything in a NODE_ENV=test only row above is then left with no signal.

Preloading varlock ahead of the runner. With node --import varlock/auto-load or NODE_OPTIONS, varlock resolves in the parent process before the runner has set anything.

Whenever varlock resolves in a parent process, its values are injected as __VARLOCK_ENV and reused by the worker processes. A wrong result there propagates to every worker, even ones that would have detected test on their own.

If you depend on VARLOCK_ENV=test to load .env.test or toggle behavior via forEnv(test), explicitly pass it when running tests:

VARLOCK_ENV=test bun run test
# or
VARLOCK_ENV=test varlock run -- vitest

This is the same pattern recommended for any environment flag. See the environments guide for more details.