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

# Compose and test fragments

Use route cache hints and schema-2 manifests to compose trusted fragment HTML at the edge, then test the production transport in process.

Use fragments for body content such as shared chrome, banners, or booking widgets whose cache lifetime
differs from the page shell. Do not use them for head metadata or repeated list rows. Fragment
transport is HTML-only; a page's semantic Markdown callback owns all non-HTML semantics.

## Cache and compose at the edge

Declare cache-policy names in `defineBrixServer`; `cache` only emits an edge hint. An omitted value or
`cache: false` is uncached. Brix does not store responses, choose TTLs, or purge entries. Public cached
fragments must not vary on undeclared cookies, authorization, tenants, locale, or experiments. Use a
private policy or complete partitioning for authenticated output.

Page-shell query policy remains independent. Forwarding `campaign` to a fragment does not prove that
the shell ignores it. By default each declared page query varies the shell key; `shellIndependent`
excludes reviewed values, `bypass` disables caching when a value is present, and undeclared query
bypasses caching. See [caching](/docs/caching) for the distinction from application data caches.

Production builds export `brixManifest` beside `app`. Schema 2 describes fragment transport, pages,
representations, auth, cache hints, and query policy. A central edge merges manifests by service,
rejects route and policy collisions, routes the request, and applies its own storage policy.

For composition, the edge requests the shell with `x-brix-fragments: defer`. Brix emits inert
`template` placeholders and adds `Vary: x-brix-fragments` only when it encountered a fragment. The
provider-neutral `composeFragments` helper resolves same-origin sources concurrently and inserts the
HTML. Pass the live page URL whenever query forwarding is possible.

The composer rejects malformed or cross-origin sources, recursion, duplicate names, failed or
non-HTML fragments, and size/count overruns. Defaults are 20 fragments, a 2 MB shell, and 512 KB per
fragment; adjust `maxFragments`, `maxPageBytes`, and `maxFragmentBytes` only from measured needs. Add
provider-level origin timeouts.

Fragment endpoints can contain islands. They return scoped HTML with inert hydration metadata, and
the assembled page bootstrap hydrates immediate, idle, and lazy roots without executable fragment
scripts.

## Test transport and composition

The generated harness exposes `testFragment`, `testPage`, and typed `mockFragment`:

```ts
const endpoint = await testFragment(BookingWidgetFragment, {
  params: { hotelId: "hotel-1" },
  pageQuery: { campaign: "summer" },
});

const composed = await testPage(bookingPageRoute, {
  query: { campaign: "summer" },
  fragments: [
    mockFragment(
      BookingWidgetFragment,
      ({ params, pageQuery }) => `${params.hotelId}:${pageQuery.campaign}`,
    ),
  ],
});

```

`testFragment` exercises validation and endpoint loading. `testPage` sends the real defer header and
runs production composition in process. A mock sees only public params and forwarded query, never
server-loaded props. Test real routes for integration and mocks for deterministic parent-page cases;
missing registration, transport violations, and endpoint failures should fail tests.

Deferred URLs use Brix's reserved `__brix_locale`; endpoint schemas cannot declare it and
requests validate one configured locale. Schema-2 manifests may expose finite fragment locales so
edge cache keys partition them; legacy opaque locale metadata fails closed.

```sh
brix test src/features/chrome/components/siteHeader.fragment.test.ts
brix check
brix build

```

See [testing](/docs/testing) for harness setup and [Markdown representations](/docs/markdown) for the
explicit semantic boundary.