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

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.

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

See testing for harness setup and Markdown representations for the explicit semantic boundary.