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