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

# 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](/docs/deployment-runtime.md).
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

```sh
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`

```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](/docs/deployment-terraform.md)
for shared local/CI approval, concurrency, and recovery policies.

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

```sh
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`](/docs/markdown-pages.md#serve-markdown-serialized-ahead-of-time):
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](/docs/api-documentation.md) adds its roughly 2 MB of assets only when the server imports
`brix/server/swagger-ui`. Consult the
[upstream SDK changelog](https://github.com/fastly/js-compute-runtime/blob/main/CHANGELOG.md)
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.
