Loading and testing environments
Select environment layers explicitly for local commands, workspace members, scripts, and production-shaped tests.
First complete the schema and generated type. Then decide whether the current task is a development server, provider-free unit test, managed E2E server, or script—the correct command and inclusion of local overrides differ for each.
Load environments explicitly
#brix dev
brix dev --stage production
brix dev --stage production --no-local
brix dev --no-env
brix test
brix test --env
brix test --stage pre-prod --project node
brix build
brix build --stage production --no-local
brix env run development -- run scripts/seed.ts
What each form loads:
brix devresolves thedevelopmentstage with local overrides;--stageselects another stage and--no-localdrops the local layers.brix dev --no-envskips resolution and is meant only for a process that already inherited a resolved environment.brix testresolves nothing by default.--envloads thetest-runstage;--stage <stage>selects another.brix buildresolves nothing by default and has no implicit stage: pass--stage <stage>when the build needs configuration.brix build --envis rejected sotest-runvalues can never reach a deployable build by accident.--no-localrequires--envor--stagefor tests, and--stagefor builds.- Managed E2E is different: when no resolved environment was inherited, its server loads the
test-runstage including.env.localand.env.overrides. Keep that stage provider-free with fake values if E2E must run offline.
test-run is reserved for test values: brix build --stage test-run, brix env run test-run -- build,
brix env export test-run, brix env upload test-run, and a test-run promotion stage are
rejected. Any other name, including test, is an ordinary deployment stage, so a deployed test
environment's configuration never reaches brix test --env or managed E2E.
Loading order is schema, base, selected stage, local, overrides, then process values. --no-local, brix env export, and brix env upload select only schema, base, and stage. There is no implicit root .env, bare .env, or .env.<stage>.local discovery.
In a workspace, select the owning application on the outer command:
brix dev#booking
brix env#booking run development -- run scripts/seed.ts
brix env#booking upload production --account 123456789012 --region eu-west-1
Each application owns its schema and generated type; there is no sibling or workspace-root fallback.
Unlike local loading, brix env export and brix env upload reject an ambient process value for an
application key unless you consent to it with repeatable --allow-override KEY; internal provider
authentication is allowed. Both also refuse to run inside an injected brix env run environment.
For multi-application deployment, prepare all environments before any write with brix/env/upload,
not sequential CLI uploads; see Terraform-first deployment.
brix env run accepts exactly one stage and a Brix command after --. The command cannot be
another brix env command or carry a workspace selector; put the selector on env instead.
Before Varlock resolves providers, Brix rejects a target that is not a Brix command and reserved
names declared in the schema. Before the injected command runs, it rejects a resolved STAGE that is
sensitive or differs from the selected stage, and reserved names from any layer. The same checks
apply to brix dev, brix build --stage, and brix test --env.
Resolving a stage also fails while SECRETS_ARN or SECRETS_VERSION is set, because loadEnv()
would read that deployed AWS snapshot instead of the selected stage. This matters in a GitHub job
after brix env upload exports the pair: unset both (or use a separate job) before a later
brix env run, brix dev, brix build --stage, or brix test --env step. The managed E2E
server applies the same check before it resolves the test-run stage.
The Varlock wrapper forwards SIGINT and SIGTERM it receives to its child and waits for the child
to exit. Put graceful cleanup in the child application's signal handling rather than assuming
Varlock exits immediately after forwarding a signal.
Read configuration in a script
#Generated applications provide a typed loadEnv binding in src/env.script.ts. A script imports
that binding, rather than reading process values or importing the inert server declaration:
import { loadEnv } from "#brix/env/script";
const env = await loadEnv();
const response = await fetch(env.CATALOG_URL, {
headers: { authorization: `Bearer ${env.CATALOG_TOKEN}` },
});
if (!response.ok) throw new Error(`Catalog check failed (${response.status})`);
This example uses the keys from the schema guide. Run it with explicit stage selection:
brix env run development -- run scripts/check-catalog.ts
The outer command resolves the selected files and providers; loadEnv() reads that resolved
payload and reuses it for later calls in the same process. Plain brix run scripts/check-catalog.ts
does not load dotenv files and fails with "No validated environment is available" when neither a
resolved payload nor an exact AWS snapshot is present. This includes steps after brix env export:
exported keys are plain process variables, not a resolved payload, so read them from process.env
or resolve again with brix env run. Scripts in deployment jobs may instead read the exact
SECRETS_ARN/SECRETS_VERSION pair using their own AWS identity. Never print the returned object
or response bodies that may contain credentials.
Start a production build locally
#brix start serves an existing Node build from dist/app.mjs. It loads no dotenv files itself:
each request reads configuration from the same sources as loadEnv(). To smoke a production build
on your machine, resolve the stage around the command:
brix build --platform node
brix env run production --no-local -- start
start reads only HOST (default 0.0.0.0) and PORT (default 3000) from its own process, and
sets NODE_ENV=production when unset. A deployed Node process instead receives the exact
SECRETS_ARN and SECRETS_VERSION pair and an AWS identity that can read that version; see
secrets and deployment snapshots. Without either source, requests fail
with a 500 rather than falling back to process values.
Test safely
#Keep unit tests independent of secret providers. Supply environment fixtures through the harness without replacing modules or bypassing production validation:
import { createTestHarness } from "brix/test";
import { createBrixApp } from "brix/server";
import { brixServer } from "#brix/server";
export const { testApi, testFragment, testPage, testResponse, withOptions } = createTestHarness({
createApp: () => createBrixApp(brixServer),
env: {
STAGE: "test-run",
PORT: 3000,
CATALOG_URL: "http://catalog.test",
CATALOG_TOKEN: "fixture-catalog-token",
},
});
This is the generated #brix/test binding with fixture values for the schema guide's keys. Handlers
and loaders consume the fixture through c.env, using the same request adapter and snapshot
parser as production. That parser validates the snapshot envelope, JSON values, and permitted key
names; it does not execute the Varlock schema or enforce the generated TypeScript type at runtime.
Keep fixture values consistent with the authored schema. Test schema constraints separately by
loading the test-run stage with brix test --env --project node. Use sufficiently long fake sensitive
values in env/.env.test-run, and never print resolved configuration. See
server setup and Contentful for safe consumption.
Custom Lambda initialization
#A declared custom Lambda entry uses defineLambdaHandler({ env, create }) from brix/lambda,
with the inert env declaration imported from #brix/env. It does not use the script-only
#brix/env/script loader. Only the declared entry may import the Lambda wrapper; HTTP routes
continue to read c.env.
Imports and builds stay provider-free. The first invocation loads the exact
SECRETS_ARN/SECRETS_VERSION snapshot and calls the factory with resolved configuration.
Concurrent calls share initialization, successful initialization is cached, and initialization
rejection allows a later retry. Both selectors are required: there is no AWSCURRENT, ambient
application-value override, or Varlock fallback.
Normal tests inject configuration into the application factory and call its raw event handler.
Wrapper tests and deployed Lambda invocations can exercise the exact snapshot boundary.
Custom-handler brix dev is unsupported; use direct tests or an event runner. See
custom Lambda setup and 2.1/2.2 migration.
When local and test loading is predictable, continue to secrets and deployment snapshots.