> [Agent navigation index](/llms.txt)

# 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`

```dotenv
# 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:

```sh
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`

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