Skip to content
brix.v2.15.0+b120c49

Search documentation

Loading search…

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

    Environment schemas and types

    Author the canonical Varlock schema, generate TypeScript declarations, and consume validated request configuration through Brix.

    Start in a full-stack application with an env/ directory. This task is complete when brix env types updates the committed declaration and brix check accepts both files; provider credentials are not needed for type generation.

    Create the schema

    #

    Keep .env.schema, optional .env.base, safe .env.<stage> files, and shared .env.local under env/. Ignore only env/.env.overrides for personal overrides. Never commit resolved secrets.

    env/.env.schema
    # @currentEnv=$VARLOCK_ENV
    # @generateTsTypes(path=../src/env.generated.d.ts, auto=false, exposeEnv=none, processEnv=none, importMetaEnv=none)
    # ---
    
    # @internal @sensitive=false
    VARLOCK_ENV=development
    
    # @type=string @required @sensitive=false
    STAGE=$VARLOCK_ENV
    
    # @type=number @required @sensitive=false
    PORT=3000
    
    # @type=url @required @sensitive=false
    CATALOG_URL=https://catalog.example.com
    
    # @type=string @required @sensitive
    CATALOG_TOKEN=
    

    The required token intentionally has no default. Before running brix dev, provide a valid provider reference or a safe local fixture in the appropriate value file. For the offline test-run stage that brix test --env and managed E2E load:

    env/.env.test-run
    CATALOG_URL=http://catalog.test
    CATALOG_TOKEN=fixture-catalog-token
    

    These values are only configuration fixtures; they do not start a catalog service. Route tests inject fixtures directly, while HTTP-consuming tests still need an MSW handler or a disposable real service.

    Declare every application key and type in the schema. Stage and local files supply values, not validation. Mark selection and provider inputs @internal so they stay out of application types and deployment snapshots.

    Follow naming rules

    #

    STAGE must be non-sensitive and equal the selected stage; loading and upload fail otherwise. Stage names are lowercase identifiers that start with a letter and may contain digits and hyphens; schema, base, local, and overrides are reserved file roles, not stages.

    Application keys must match [A-Za-z_][A-Za-z0-9_]*. Brix reserves names that shells, Git, SSH, Terraform, language runtimes, and CI read as executable hooks, trust roots, search paths, or credentials, because validated values can reach child processes and later CI steps. Reserved names are compared case-insensitively and fail loading, upload, export, and runtime parsing with an error that names the key.

    • Reserved prefixes: ACTIONS_, AWS_, BASH_, BRIX_, COREPACK_, CURL_, DOCKER_, DYLD_, GH_, GITHUB_, GIT_, INPUT_, LD_, NPM_, NUB_, OP_, PERL, PNPM_, PYTHON, RUNNER_, SSH_, STATE_, STORYBOOK_, TF_, VARLOCK_, VITE_, XDG_, YARN_, __NUB_, __VARLOCK_.
    • BRIX_SERVICE_SIGNING_KEYS and BRIX_SERVICE_VERIFY_KEYS are the only BRIX_ names an application may declare, in exactly that case. They are the standard names for service signature keys, which Brix reads from application configuration; every other BRIX_ name stays reserved. They must be declared @sensitive: Brix refuses them as non-sensitive items, deployment bindings, or CI literal exports.
    • Reserved exact names: ALL_PROXY, BROWSER, CDPATH, CI, CLASSPATH, EDITOR, ENV, FTP_PROXY, GCONV_PATH, GLOBIGNORE, GNUPGHOME, HISTFILE, HOME, HOSTALIASES, HTTP_PROXY, HTTPS_PROXY, IFS, INPUTRC, JAVA_TOOL_OPTIONS, JDK_JAVA_OPTIONS, _JAVA_OPTIONS, KUBECONFIG, LESSCLOSE, LESSOPEN, LOCALDOMAIN, MANPAGER, NETRC, NO_PROXY, NODE_AUTH_TOKEN, NODE_EXTRA_CA_CERTS, NODE_OPTIONS, NODE_PATH, NODE_REPL_EXTERNAL_MODULE, NODE_TLS_REJECT_UNAUTHORIZED, OPENSSL_CONF, PAGER, PATH, PROMPT_COMMAND, PS1, PS4, REQUESTS_CA_BUNDLE, RES_OPTIONS, RUBYLIB, RUBYOPT, SECRETS_ARN, SECRETS_VERSION, SHELL, SHELLOPTS, SSL_CERT_DIR, SSL_CERT_FILE, SUDO_ASKPASS, TEMP, TMP, TMPDIR, VISUAL, WGETRC, ZDOTDIR.

    VITE_ is reserved because Vite inlines prefixed process variables into browser import.meta.env. Brix additionally sets Vite's envPrefix to a reserved BRIX_ sentinel, so ambient VITE_* variables from a shell or CI step never reach browser bundles; pass browser constants through vite.define instead. STORYBOOK_ is reserved for the same reason: Storybook appends it to envPrefix, so a schema value exported to a later CI step would otherwise be inlined into the Storybook bundle.

    A non-internal schema key with a reserved name fails before Varlock starts any child process, and brix doctor reports it against env/.env.schema.

    Rename a colliding application value, for example GIT_SHA to COMMIT_SHA. NODE_ENV and other unlisted NODE_ names remain available. Provider credentials such as OP_SERVICE_ACCOUNT_TOKEN belong in @internal inputs, which never enter a snapshot.

    Useful decorators include @type=string, number, boolean, url, or enum(...); @required and @optional; @sensitive and @sensitive=false; @internal; @example; and @docs(...). Varlock defaults sensitivity to true, so classify values explicitly. @public means non-sensitive metadata—it does not expose a value to browser code.

    Sensitive values must be safe to redact. An explicitly sensitive value shorter than 12 characters warns; one shorter than 3 characters errors, as do unsuitable values such as booleans, numbers, and non-string composite elements. Keep numeric-looking secrets as strings. If a real secret is 3–11 characters, acknowledge it with @sensitive={allowShortValue=true}; that option cannot allow fewer than 3 characters. Values swept in by @defaultSensitive warn instead of failing, but explicit classification remains the supported application pattern.

    URL domain allowlists match the entire host. Entries contain a hostname and optional port, without a scheme, credentials, or path. Omitting the port permits any port; including it pins that port. Use an array for multiple hosts:

    # @type=url(allowedDomains=[localhost, api.example.com:8443]) @required @sensitive=false
    SERVICE_URL=http://localhost:3000
    

    Varlock warns on malformed URLs, whitespace or control characters, missing hosts, and non-HTTP(S) protocols without explicit allowedProtocols; its next major turns these warnings into errors, so fix them now. Domain allowlists already reject ambiguous host spellings: use scheme://host, canonical IPv4, and punycode for internationalized hosts. Do not weaken an allowlist to silence validation. Declare intentional non-HTTP protocols explicitly. allowedProtocols="*" and allowNoHost=true are opt-in exceptions, not Brix defaults.

    Write regular-expression constraints with regex("pattern", "flags"), such as @type=string(matches=regex("^[0-9a-f]{7,40}$", "i")). Plain or /pattern/ strings are deprecated; pass an unwrapped pattern to regex().

    Unquoted values shaped like function calls are parsed as resolvers such as op(...), and malformed ones fail validation rather than becoming literal text. Quote literal values that contain parentheses, for example RELEASE_LABEL="beta (2)".

    Redaction and optional Varlock features

    #

    Use the root @redact decorator to configure log redaction; @redactLogs is a deprecated alias that warns. Commands Brix runs through Varlock (brix env run, brix dev, brix build --stage, and brix test --env) redact sensitive values from child stdout/stderr by default whenever that stream is piped or redirected, as in CI; interactive terminals are not rewritten. Machine-readable output that echoes a secret is therefore rewritten in CI. Set # @redact(stdout=false) in the schema to disable stdout/stderr redaction. Do not exempt secrets from redaction merely to remove warnings. Brix does not redact browser traces or arbitrary application artifacts.

    Leave Varlock's default environment injection enabled. Brix commands and script loadEnv() read that injected payload; Varlock's encrypted environment freezing is not a Brix transport and does not replace exact-version deployment snapshots. Type generation never contacts providers.

    Generate and consume types

    #

    Brix refreshes schema-only types before dev, test, build, run, exec, watch, and dlx workflows, even when those commands do not resolve providers. Generate explicitly after schema edits:

    brix env types
    

    Commit src/env.generated.d.ts, but never edit it. brix check, brix doctor, and brix ci report missing or stale output without writing it.

    At a workspace root, use the member-scoped repair printed by doctor, for example brix env#apps/backend types. Plain brix env types runs only inside an application; it does not regenerate every member. A missing member declaration produces one environment-type diagnostic.

    src/env.server.ts
    "use server";
    
    import { createEnv } from "brix/env";
    import type { CoercedEnvSchema } from "./env.generated.d.ts";
    
    export const env = createEnv<CoercedEnvSchema>();
    

    Server setup passes this declaration to defineBrixServer, and request modules read validated values from c.env. Do not read process.env in features or import environment values into islands. Application rules remain in .env.schema. Doctor also rejects destructuring env from the global process, imported process bindings, and statically traceable const aliases in application runtime modules. Locally shadowed names are not treated as Node's process. This is bounded static detection, not whole-program data-flow analysis: it does not follow mutable aliases or computed property names that require evaluation. Test modules and scripts outside src/ retain their environment-access exemption; scripts should use the explicit typed loader described in environment loading.

    Validation has two stages. Varlock applies application types, requiredness, and constraints when loading or uploading values. At runtime, createEnv checks the snapshot envelope and allowed keys, then deeply freezes its values; the TypeScript generic does not repeat the authored schema's validation. Ship code and generated types with a snapshot produced from the matching schema, and restrict snapshot writes to the trusted publication workflow.

    If check reports stale types, run brix env types, review the generated diff, and commit it with the schema change. If loading fails, fix the reported key or provider authentication rather than weakening @required or marking a secret public to make the command pass.

    Next, select authored values for commands and tests in loading environments.