Server & Environment Configuration

Complete configuration reference for brick() server options, environment variables, and secrets.

This reference documents all configuration options for the brick() HTTP server runtime, CLI environment variables, and secrets management.

`CreateServerOptions` for `brick()`

When constructing the server gateway via brick(options), configure the following settings:

Option	Type	Default	Description
`port`	`number`	`undefined`	Accepted by the type but not read by `brick()`. Pass the port to `app.listen(port)` instead.
`prefix`	`string`	`"/api"`	Base path prefix for service action routes (`${prefix}/<service>/<action>`) and plugin routes.
`services`	`Service[]`	All registered services	Array of services to mount. Defaults to `getGlobalRegistry().list()`.
`title`	`string`	`"Brick-TS API Mesh"`	Application title rendered in OpenAPI 3.1 and documentation headers.
`version`	`string`	`"1.0.0"`	Application API version in OpenAPI `info.version`.
`description`	`string`	`undefined`	Narrative API description for OpenAPI specifications.
`docs`	`boolean`	`true`	Enables or disables the OpenAPI specification, Scalar, and Swagger UI routes.
`openApiPath`	`string`	`"/openapi.json"`	Path where raw OpenAPI 3.1 JSON is served. Not affected by `prefix`.
`docsPath`	`string`	`"/docs"`	Path where Scalar interactive API documentation is mounted. Not affected by `prefix`.
`swaggerPath`	`string`	`"/swagger"`	Path where Swagger UI documentation is mounted. Not affected by `prefix`.
`requestLogging`	`boolean \| RequestLoggingOptions`	`true`	Logs `METHOD path → status (ms)` per request. Options: `{ enabled?: boolean; logger?: (msg: string) => void }`.
`reference`	`boolean \| ReferenceOptions`	`false`	`true` mounts a Scalar page at `/reference`. Options mount one only with a `path`; `documents` adds OpenAPI documents to the dashboard's APIs tab.
`compiler`	`boolean`	`true`	When true, generates specialized request handlers at server construction; `false` uses the generic handler.
`compilation`	`CompiledApplication`	`undefined`	Precompiled handlers (used by the bundle that `brick build` emits).
`secrets`	`{ source?, validate? }`	`undefined`	Secret source and boot validation. `resolveSecrets()` runs at construction unless `validate: false`.
`endpoints`	`EndpointDefinition[]`	`undefined`	Raw HTTP routes mounted outside the JSON action mesh.
`dashboard`	`DashboardOptions`	`undefined`	Read-only monitoring dashboard `brick start` serves on its own port, behind `auth`. Options: `{ port?: number; host?: string; auth?: { token?: string \| string[]; authorize?: (request: Request) => boolean \| Response \| Promise<boolean \| Response> }; historyDays?: number }`. Required `auth` beyond loopback; turns on `telemetry`. See Monitoring Dashboard.
`documentation`	`string \| DocumentationOptions`	`undefined`	Folder of `.md`/`.mdx` pages shown in the `brick dev` dashboard's Docs tab. Options: `{ dir: string; components?: string }`. Relative paths start at the app entry's folder. Needs `fumadocs-core` and `@mdx-js/mdx`.

brick() always mounts GET /_health and GET /_brick/services at the root, regardless of prefix.

Environment Variables

The framework and CLI inspect the following environment variables:

`PORT`

Used by: brick dev, brick start, and compiled bundles (dist/brick/server.js). brick() itself does not read PORT.
Precedence: For dev/start, an explicit --port <number> flag wins over PORT, which wins over the default 4000. Compiled bundles use PORT, falling back to the --port value given to brick build (default 4000).
Constraints: Must be an integer between 1 and 65535. Out-of-range values or non-numeric strings make the process exit with an error.

Secrets Management (`@brickkit/core`)

Brick-TS includes a secret referencing utility. Each secret() call registers a reference; values resolve from process.env (or a custom SecretSource) when you read them. A secret without a default is required:

src/secrets.ts

import { secret, resolveSecrets } from "@brickkit/core";

// 1. Declare references to environment variables:
export const dbPassword = secret("DB_PASSWORD");
export const apiKey = secret("STRIPE_API_KEY").default(""); // a default makes it optional
export const port = secret("PORT").default("4000").transform(Number);

// 2. Access secrets at runtime:
const password = dbPassword.require(); // Throws if missing or invalid
const key = apiKey.value(); // Returns the value, or undefined when unset

// 3. Validate all declared secrets (brick() also does this at construction):
resolveSecrets(); // Throws one error listing every missing required secret

SecretRef methods: .default(value), .transform(fn), .validate(fn), .url(), .value(source?), .require(source?), and .isSet(source?). listSecrets() returns { name, hasDefault, isSet } metadata without values.

Overriding Secrets in Tests

In integration tests, override secret values without mutating process.env:

test/helpers.ts

import { overrideSecret, resetSecrets } from "@brickkit/core";

overrideSecret("DB_PASSWORD", "test-secret");

// Clears all overrides AND the secret registry:
resetSecrets();

Server & Environment Configuration

CreateServerOptions for brick()Copy Anchor Link

Environment VariablesCopy Anchor Link

PORTCopy Anchor Link

Secrets Management (@brickkit/core)Copy Anchor Link

Overriding Secrets in TestsCopy Anchor Link

On this page

`CreateServerOptions` for `brick()`

Environment Variables

`PORT`

Secrets Management (`@brickkit/core`)

Overriding Secrets in Tests