Skip to content
brix.v2.15.0+b120c49

Search documentation

Loading search…

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

    Deploying to Cloudflare and Fastly

    Deploy fully bundled worker graphs to Cloudflare Workers or Fastly Compute with provider-owned assets, snapshots, and storage bindings.

    Use this guide after choosing a platform and snapshot boundary. Cloudflare needs an ASSETS binding and serialized snapshot; Fastly additionally needs its CLI, an exact Secret Store revision, and an asset backend. Brix does not authenticate to or deploy either provider.

    Cloudflare Workers

    #
    brix build --platform cloudflare
    

    Deploy dist/app.mjs with a string BRIX_ENV_SNAPSHOT binding and an ASSETS fetcher binding. The production bundle is a native, fully bundled Worker graph and cannot import Node APIs or the DynamoDB adapter. The build rejects a Node builtin such as fs or node:fs only when it would reach the server bundle unresolved: package browser mappings and installed polyfill packages such as events or buffer remain usable, and browser island bundles follow Vite's normal client resolution. Brix does not generate or run a provider deployment command. Local brix dev still executes through Node rather than workerd.

    The assembled-app initialization gate used by Node and generated HTTP Lambda builds does not validate Cloudflare output. A successful Cloudflare build is not proof that Worker initialization or route registration succeeds; exercise the built bundle in a Worker runtime before deployment.

    Configure the asset binding's file layout for Brix's path rewrite: with the default /_brix/ prefix, a browser request for /_brix/chunk.js is forwarded to ASSETS as /chunk.js. Upload the generated asset directory (assetOutDir, dist/_brix by default) at that binding's root, rather than nesting another _brix directory, and exclude its build metadata (.vite/ and brix-island-manifest.json), which is not a browser asset. The Worker answers only GET and HEAD under the prefix; other methods receive 405. An absolute CDN assetPrefix such as https://cdn.example.com/shop/ is served only for requests to that origin, so application routes under /shop/ on your own origin keep reaching the router. Root public URLs need your own provider delivery routing. Verify both a page and its actual asset requests in a Worker runtime before switching traffic.

    The environment binding contains serialized brix-env-v1 JSON, not one string per application key. Publish it through trusted deployment tooling; Brix's upload command is AWS-only. Application values must already have passed the authored schema validation. Never embed secrets with Vite define or into the Worker source merely to avoid configuring bindings.

    Use native Cloudflare bindings

    #

    Handlers see the validated environment on c.env, not the Worker env object, so KV, D1, R2, Queue, Durable Object, and service bindings are not on c.env. Read them with getPlatformBindings(c) from brix/server, which returns the bindings object passed to the Worker. Its type parameter only describes the result; Brix does not validate it. In this example SessionStore stands for your binding type, such as KVNamespace from @cloudflare/workers-types:

    src/features/sessions/sessions.server.ts
    "use server";
    
    import { getPlatformBindings } from "brix/server";
    import { brixServer } from "../../brix.server.ts";
    
    export const getSessions = brixServer.createService((c) => {
      const sessions = getPlatformBindings<{ SESSIONS?: SessionStore }>(c)?.SESSIONS;
      if (!sessions) throw new Error("SESSIONS binding is not configured");
      return sessions;
    });
    

    The returned object also contains BRIX_ENV_SNAPSHOT and ASSETS, which Brix owns; do not read them. brix dev runs on Node, where Cloudflare bindings are absent, so give local development an alternative or fail clearly as above. Call getPlatformBindings only with a request context created by createBrixApp; other values throw.

    Fastly Compute

    #

    Verify the handoff offline with Node-only brix/artifacts and target fastly-compute before publishing and before an approved apply. Verification checks tarball integrity without extraction; it does not attest provenance. Use project-owned Terraform/provider tooling for resources and traffic, not the AWS-only snapshot uploader. See Terraform-first deployment for shared local/CI approval, concurrency, and recovery policies.

    Install the Fastly CLI on PATH, then use either configuration or the CLI flag:

    BRIX_ENV_REVISION=release-2026-09-09 brix build --platform fastly
    

    Production Fastly builds require BRIX_ENV_REVISION even if the application declares no environment keys. It is a non-secret exact selector for the brix-env Secret Store key, not a resolved secret, and may contain only letters, numbers, ., _, :, and -. Development uses a local revision automatically. The build automatically runs Fastly packaging, retains dist/fastly for Viceroy, and emits dist/deployment/package.tar.gz, deployment.json, and assets/; do not run a second fastly compute build. The package is an exact copy of the CLI-produced tarball. The schema-1 manifest identifies fastly-compute, build/source identity, package size and SHA-256, and each asset's path, public URL, content type, cache policy, size, and SHA-256. BRIX_ASSET_BACKEND names the asset backend and defaults to assets. Asset requests to the backend (and to the Cloudflare ASSETS binding) are new GET/HEAD requests that carry only Accept, Accept-Encoding, Range, and conditional headers, never viewer cookies or authorization; Set-Cookie from the backend is dropped. Generated build metadata is excluded from the handoff's published assets. Brix overrides that backend during development and neither publishes nor provisions it in production. Resolved secrets are never included in the production package.

    Brix pins the Fastly JavaScript SDK (@fastly/js-compute 4.3.0) and runs it through its own toolchain, which compiles ahead of time (AOT) by default; do not install or invoke another SDK version for a Brix application. The AOT build snapshots everything the server creates while its modules load into the Wasm, and Fastly refuses packages above 100 MB uncompressed, so brix build fails beyond that limit. Parse or render large bundled content on first use rather than at module load, and prefer to precompile large content such as documentation into generated release assets that the server reads from storage, so neither the content nor its compiler is bundled. Every request runs in a fresh instance created from that snapshot, so caches filled during a request do not survive and per-request work repeats each time. Serialize Markdown representations ahead of time with md.serializedDocument: the documentation site stores each guide's serialized Markdown in its release asset, which cut its Markdown responses, up to several hundred milliseconds for its longest guide, to roughly the cost of its HTML pages. Bundled source also grows the compiled code, so import only the server features you serve: Swagger UI adds its roughly 2 MB of assets only when the server imports brix/server/swagger-ui. Consult the upstream SDK changelog when a Brix upgrade changes the pinned version.

    Brix enables the SDK's HTTP cache hooks at compilation (--enable-http-cache). Viceroy does not implement the HTTP cache API, so application-owned cache hooks need a local bypass and a deployed edge test. Enabling hooks does not change the default Brix asset adapter's cache bypass.

    Generated assets use a fresh releases/<UUID>/ beneath assetPrefix; authored public files retain root URLs. Publish assets before activating the runtime and retain rollback assets. Brix has no Fastly deploy command and requires no deployment credentials. Fastly local development adds no release URL and emits no handoff, preserving its backend mapping.

    For production SSR sites, prefer Compute for application code and an S3-compatible object store for immutable browser assets. Keep small application-owned endpoints such as an installer bundled with the application. Fastly Object Storage is private: it requires SigV4 signed requests and read-only runtime credentials, separate from upload credentials. Merely pointing assets at its regional endpoint is not sufficient. The default Brix asset adapter forwards unsigned requests and bypasses the fetch cache; use an authenticated asset gateway or application-owned asset middleware with assets: false, explicit public-path restrictions, signing, and successful-response caching. Root public URLs need delivery routing too. Storage provisioning, upload verification, credential rotation, cache policy, domain/TLS setup, and rollback retention remain application-owned.

    An optional project-root fastly.toml contributes local_server fixtures only. Relative fixture file paths resolve from the project root. Unrelated upstream backend, KV, and Secret Store fixtures are retained, while Brix overrides the selected asset backend. If Varlock supplied a local snapshot, it overrides the brix-env fixture; otherwise an authored fixture is used, and if neither exists Brix supplies an empty snapshot. The generated Viceroy manifest and resolved snapshot live in a mode-0600 manifest inside a mode-0700 temporary directory outside the project.

    Fastly KV is the native supported shared data cache in Fastly development and production. It has no strong-read option and its invalidation is eventual; it does not purge CDN or browser caches.

    The task is complete when the provider runtime serves an SSR response, generated asset URLs, and the intended snapshot revision. Smoke those on the public candidate before switching traffic, and retain the previous package, assets, and snapshot together for rollback.