Skip to content
brix.v2.15.0+b120c49

Search documentation

Loading search…

    Documentation menu
    Docs / Deployment and releases / DeploymentRead Markdown
    On this page

    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:

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

    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:

    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:

    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. 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, a typed API route, and assets used by islands. Preserve x-request-id through proxies. See environment configuration, caching, and testing. 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 for a Node runtime, or Cloudflare or Fastly for a bundled Worker graph.

    When enabling Contentful client loading, 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.