Skip to content
brix.v2.15.0+b120c49

Search documentation

Loading search…

    Documentation menu
    Docs / Server configuration / Environment and secretsRead Markdown
    On this page

    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 dev resolves the development stage with local overrides; --stage selects another stage and --no-local drops the local layers. brix dev --no-env skips resolution and is meant only for a process that already inherited a resolved environment.
    • brix test resolves nothing by default. --env loads the test-run stage; --stage <stage> selects another.
    • brix build resolves nothing by default and has no implicit stage: pass --stage <stage> when the build needs configuration. brix build --env is rejected so test-run values can never reach a deployable build by accident.
    • --no-local requires --env or --stage for tests, and --stage for builds.
    • Managed E2E is different: when no resolved environment was inherited, its server loads the test-run stage including .env.local and .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:

    scripts/check-catalog.ts
    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:

    src/test/harness.ts
    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.