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

# Deployment builds and runtime configuration

Understand platform selection, development and production build differences, and the environment snapshot boundary shared by every adapter.

Prerequisites: the application builds on its default target, `brix verify` passes, and the deployment
owner has chosen where runtime snapshots and browser assets will live. Building here creates local
artifacts only; it does not publish or activate them.

Select a platform in `vite.config.ts`:

```ts
import { defineBrixConfig } from "brix/vite";

export default defineBrixConfig({ platform: "cloudflare" });

```

Or select it for one invocation:

```sh
brix build --platform cloudflare
brix dev --platform fastly

```

The CLI `--platform` value wins over `defineBrixConfig({ platform })`; the configuration wins over the `node` default. The flag applies only to full-stack applications; in a workspace, select the member (`brix build#storefront --platform lambda`). `brix verify` runs diagnosis, checks, tests, and the configured production build. Use `brix ci` when CI also needs a clean, lockfile-exact installation. Brix builds artifacts only; provider publication and activation remain consumer-owned.

## Development and build behavior

Node, generated HTTP Lambda, and Cloudflare development use Brix's Node-based Vite development server. In
particular, `brix dev --platform cloudflare` does **not** emulate workerd; use provider integration
coverage in addition to local development. Their production outputs differ:

- `node` emits a Node ESM server in `dist/app.mjs` plus browser assets.
- `lambda` emits the same assembled HTTP application in `dist/app.mjs` with a native `handler`
  (`app.handler`) and packages the runtime and public assets under `dist/deployment/`.
- `lambda` with `handler: "src/handler.ts"` instead emits a fully bundled Node `dist/handler.mjs`
  (`handler.handler`), without routes, islands, Panda, or public assets. This replaces the HTTP build.
- `cloudflare` emits a fully bundled, Node-free Web Worker graph.
- `fastly` emits a fully bundled worker graph, compiles it with Brix's pinned Fastly JavaScript SDK,
  retains `dist/fastly`, and creates `dist/deployment/package.tar.gz`, `deployment.json`, and
  separately publishable `assets/` from the exact CLI package.

Custom-handler `brix dev` is unsupported. Use direct handler tests or an event runner; see
[custom Lambda handlers](/docs/deployment-node-aws.md#custom-lambda-handlers).

Node and generated HTTP Lambda production builds import the assembled application in an isolated
process before succeeding. Initialization errors, including conflicting routes, fail the build
before Lambda packaging. This does not dispatch requests or resolve Brix's request-lazy environment
providers; application-authored top-level code still runs. It is not a runtime health check.
Cloudflare has no equivalent initialization gate: validate its bundle in a Worker runtime.
Fastly's existing native compilation remains unchanged.

Fastly development is intentionally production-shaped. `brix dev --platform fastly` performs a
production-shaped application build with the selected environment (**development** by default), compiles Wasm, runs
it in Viceroy, and proxies the Vite address to Viceroy. Changes are serialized into complete rebuilds
and restarts. There is no state-preserving HMR or automatic browser reload. If a rebuild fails, the
last successful Viceroy instance remains available while the watcher waits for another change;
configuration restarts await cleanup before replacing the controller.
The local asset snapshot uses the build's resolved `vite.publicDir`: `"public"` by default,
a custom directory when selected, or no authored public files for `false`. If the Vite callback
returns different settings for `serve` and `build`, Fastly development uses the build selection
with the development mode. A failed rebuild keeps the prior public-file snapshot with its server.
Local Fastly builds add no release UUID and emit no deployment handoff, preserving Viceroy's asset
backend mapping. Production generated assets use `releases/<UUID>/` beneath `assetPrefix`; authored
public files keep root URLs. The `fastly-compute` manifest records build/source identity, package
size and SHA-256, and checksummed asset delivery metadata. Publish assets before runtime activation
and retain rollback assets. Brix never provisions, uploads, deploys, or needs deployment credentials.

Platform targets and environment stages are separate. Ordinary `brix build` does not load
application environment providers. Only opt into build-time values when the build actually needs
them; `--stage <stage>` can require provider credentials. `brix build --env` is rejected because a
build has no default stage. These flags do not provision resources
or activate a deployment. Use normal environment selectors with either configuration style:

```sh
brix dev --platform fastly --stage development
brix build --platform lambda --stage production --no-local

```

`brix dev` defaults to the development stage and includes local files. `--no-local` excludes local
and overrides; `--no-env` is a development-only escape hatch for an already resolved environment
and cannot be combined with `--stage` or `--no-local`. For builds, `--no-local` requires
`--stage`.

## Runtime environment

`src/env.server.ts` exports an inert declaration and `defineBrixServer` installs it:

```ts
export const env = createEnv<CoercedEnvSchema>();
export const brixServer = defineBrixServer(brix, { env });

```

The platform adapter supplies a snapshot per request, which Brix parses and exposes as deeply
frozen `c.env`. Runtime parsing validates the envelope, JSON values, and allowed keys, not the
application's Varlock rules or generated TypeScript type. Those rules run when values are loaded or
uploaded; deploy a snapshot from the matching schema revision. Request tests supply that same
snapshot boundary with `createTestHarness({ env: fixture })`; do not mock an environment singleton.
Standalone scripts use `#brix/env/script` instead.

Custom Lambda entries pass the inert `#brix/env` declaration to `defineLambdaHandler` from
`brix/lambda`. The factory receives resolved configuration on lazy first invocation, with shared
initialization, cached success, and retry after initialization rejection. Imports and builds
remain provider-free. Normal tests inject configuration into the application factory; wrapper
tests and real Lambda invocations exercise the exact snapshot boundary. The wrapper requires both
`SECRETS_ARN` and `SECRETS_VERSION`, with no `AWSCURRENT`, ambient application-value override, or
Varlock fallback. Only the declared custom entry may import it; HTTP routes stay on `c.env`.

AWS reads the exact `SECRETS_ARN` and `SECRETS_VERSION` once per process, in the region named by
the ARN, and reuses that immutable snapshot for later requests. Cloudflare receives a JSON snapshot through
the string binding `BRIX_ENV_SNAPSHOT`. Fastly reads the key named by `BRIX_ENV_REVISION` from Secret
Store `brix-env`. Brix can upload snapshots to AWS only; Cloudflare and Fastly publication and
resource bindings remain deployment responsibilities.

## Operational checks

For infrastructure delivery, follow [Terraform-first deployment](/docs/deployment-terraform.md).
Verify Lambda/Fastly handoffs offline with `brix/artifacts`, then revalidate them before applying
the digest-approved saved plan. Artifact preparation is provider-free; explicit snapshot publishing requires
authorization and is not runtime activation. Coordinate local and CI operations and retain pending,
active, and rollback inputs under a project-owned policy.

For generated HTTP applications, confirm the deployment serves an SSR [page](/docs/pages.md), a typed [API route](/docs/api-routes.md), and
assets used by [islands](/docs/islands.md). Preserve `x-request-id` through proxies. See
[environment configuration](/docs/environment.md), [caching](/docs/caching.md), and [testing](/docs/testing.md).
For custom Lambda, invoke representative raw events and assert results and failure behavior.

Treat a deployment as code, assets, and configuration together. Record their exact identities before
activation, then verify the candidate's real public URL, an error response, and an interactive page
with its JavaScript and CSS. Unit tests and a local Node server cannot prove remote bindings or
object-store permissions. If activation or smoke checks fail, inspect the provider's active version
before retrying; a failed command does not prove that nothing was published. Roll back all required
identities to a retained compatible set rather than rebuilding an old source revision.

Continue with [Node or Lambda](/docs/deployment-node-aws.md) for a Node runtime, or
[Cloudflare or Fastly](/docs/deployment-workers.md) for a bundled Worker graph.

When enabling [Contentful client loading](/docs/contentful-rendering.md#authorize-client-introduced-adapters),
provide stable Web Crypto HMAC SHA-256 keys in server bindings and a same-origin runtime for
`/_/contentful/load` and `/_/contentful/preview/grants`, even for SSG HTML. Endpoints are uncached;
add host-level aggregate rate limits. Preserve `private, no-store` on principal-bound HTML through
all caches. Retain old verification keys for cached HTML/open pages; removing a key or compatibility
generation requires coordinated invalidation, rebuilding and reload. Test signing/verification on
the actual deployment runtime: Node tests alone do not establish Worker compatibility.
