Environment schemas and types

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

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=

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.

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.

Generate and consume types

Brix refreshes types before environment-aware dev, test, build, run, exec, watch, and dlx workflows. 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.

// 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.