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.
# @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:
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_KEYSandBRIX_SERVICE_VERIFY_KEYSare the onlyBRIX_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 otherBRIX_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.
"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.