Skip to content
brix.v2.15.0+b120c49

Search documentation

Loading search…

    Documentation menu
    Docs / Server configurationRead Markdown
    On this page

    Environment and Secrets

    Brix uses Varlock for one authored environment schema per application. That schema is the source of truth for validation, generated TypeScript types, secrecy, and what reaches deployment snapshots. Loading is always explicit, so local commands, tests, and deployed runtimes each use a known stage and provider boundary.

    This applies to full-stack applications. Managed React applications have no Brix environment integration; they pass public per-mode values through vite.define, as described in the managed React guide.

    #
    1. Author the schema and generate types. Do this before writing code that reads a new key.
    2. Load a stage locally and in tests. Keep ordinary tests provider-free.
    3. Configure providers, CI exports, and immutable snapshots only for trusted deployment workflows. Use brix env export <stage> --target github for later CI steps without AWS, or brix env upload <stage> --account <id> --region <region> for an AWS runtime snapshot.

    Where each command gets its configuration

    #
    • brix dev resolves the development stage, including local overrides, through your providers.
    • brix test and brix build load no environment unless you pass --env (tests only; it loads the reserved test-run stage) or --stage <stage>. test-run holds fake test values and cannot be built, uploaded, or exported, so a deployed stage named test is unaffected by test runs. Route tests inject fixtures through the test harness instead.
    • brix env run <stage> -- <brix-command> resolves a stage for one Brix command, such as a script or a local brix start of a production build.
    • Deployed Node and Lambda runtimes read one exact AWS snapshot selected by SECRETS_ARN and SECRETS_VERSION, once per process. Cloudflare and Fastly use the same snapshot format through worker bindings.
    • Later GitHub Actions steps receive only allowlisted values from brix env export.

    Application code never reads process.env. Request handlers read validated values from c.env, and scripts call the typed loadEnv binding.

    Runtime createEnv validates the snapshot envelope and key names, then deeply freezes the values; it does not rerun your schema's application rules. Varlock enforces those rules when it loads or uploads values.

    For shared-state delivery, use Terraform-first deployment: prepare all application environments before uploads, persist idempotency tokens and receipts, and bind exact versions through project-owned Terraform. Upload requires an explicit account and region, and consent for ambient application overrides; it does not activate code or manage infrastructure state.