Skip to content
brix.v2 stable

Search documentation

70 guides

Documentation menu
Docs / Server and deployment / DeploymentRead Markdown ↗

Deployment builds and runtime configuration

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

Select a platform in vite.config.ts:

import { defineBrixConfig } from "brix/vite";

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

Or select it for one invocation:

brix build --platform cloudflare
brix dev --platform fastly

The CLI --platform value wins over defineBrixConfig({ platform }); the configuration wins over the node default. 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 deployment artifacts but does not provision provider resources or publish an application.

Development and build behavior

Node, AWS, and Cloudflare development all 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.
  • aws emits the same assembled application with a native Lambda handler.
  • 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, and automatically creates a deployable package under dist/fastly/pkg.

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.

Use normal environment selectors with either configuration style:

brix dev --platform fastly --stage development
brix build --platform aws --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.

Runtime environment

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

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

The platform adapter supplies a snapshot per request, which Brix validates and exposes as deeply frozen c.env. Request tests supply that same boundary with createTestHarness({ env: fixture }); do not mock an environment singleton. Standalone scripts use #brix/env/script instead.

AWS reads the exact SECRETS_ARN and SECRETS_VERSION. 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

Confirm the deployment serves an SSR page, a typed API route, and assets used by islands. Preserve x-request-id through proxies. See environment configuration, caching, and testing.