Author fragments
Pair an ordinary Preact component with an auto-discovered HTML endpoint sidecar and model the finite inputs that can cross its transport boundary.
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.
Start with an ordinary SSR page. A fragment adds a second way to render one component: inline with the page, or through its own endpoint when an edge composer requests deferred HTML. It does not fetch itself in the browser. Without a composer, the page still renders normally.
Generate the component and sidecar
#brix add fragment siteHeader --feature chrome
The generator writes SiteHeader.tsx, siteHeader.fragment.ts, and siteHeader.fragment.test.ts
under src/features/chrome/components/. Brix discovers any sidecar under src/features whose
filename ends in .fragment.ts and that exports exactly one PascalCase runtime value ending in
Fragment. Doctor and the build reject sidecars outside src/features, such as
src/components/header.fragment.ts, instead of silently dropping them. Add props and endpoint
inputs to the generated files:
export interface SiteHeaderProps {
transparent: boolean;
}
export function SiteHeader({ transparent }: SiteHeaderProps) {
return <header data-transparent={transparent}>Shared header</header>;
}
import { createFragment } from "#brix/server";
import { z } from "brix/zod";
import { SiteHeader } from "./SiteHeader.tsx";
export const SiteHeaderFragment = createFragment({
name: "site-header",
component: SiteHeader,
endpoint: {
params: z.object({ transparent: z.stringbool() }),
},
cache: "sharedChrome",
});
The name must be lower-case kebab-case starting with a letter. It identifies the fragment in
placeholders and serves its endpoint at /_brix/fragments/<name>; edge code reads that path from the
application manifest instead of hardcoding it.
The route is registered by exact component identity. Do not wrap or copy the component in the
sidecar, and do not register one component as two fragments: route mounting rejects it. Page JSX
imports only SiteHeader; the fragment export is a route handle for discovery and tests.
cache names an edge policy, so declare it in src/brix.server.ts first. An undeclared name is a
type error and fails when the fragment is created. Omit cache while developing without an edge
cache.
"use server";
import { defineBrixServer } from "brix/server";
import { brix } from "./brix.ts";
import { env } from "./env.server.ts";
export const brixServer = defineBrixServer(brix, {
env,
cachePolicies: ["sharedChrome"] as const,
});
export const { createFragment, createPageRoute } = brixServer;
Then render the ordinary component in a page:
import { SiteHeader } from "#/features/chrome/components/SiteHeader.tsx";
export function HomePage() {
return (
<>
<SiteHeader transparent={false} />
<main>Welcome</main>
</>
);
}
Run the page without an edge composer first: the response contains the complete Shared header markup inline. The sidecar adds a deferred endpoint for trusted composition; it does not turn the component into a browser fetch.
Render a fragment name at most once in a composed page. The composer rejects duplicate names because each fragment's hydration state is scoped by name; group repeated content behind one parent fragment or keep it in the shell. A deferred fragment also cannot sit beneath a hydrated island: deferred rendering throws so the browser never hydrates a tree that no longer matches. Move the fragment outside that island or pass it through a server-rendered slot. See islands.
Model endpoint inputs
#endpoint.params selects component props to serialize into the fragment URL.
endpoint.forwardPageQuery allowlists values copied from the live outer page URL. Both must be
finite z.object schemas with URL-serializable scalar or array outputs, their keys cannot overlap,
and every params key must exist in the component props because Brix reads those values from each
inline component instance. Keys must start with a letter or underscore, and __brix_locale is
reserved for Brix. Unknown query keys and values that fail validation return 400.
Both schemas parse URL strings, so their input must accept strings, exactly like
page query schemas. A numeric prop uses
z.coerce.number() and a boolean prop uses z.stringbool(): the inline prop false becomes
"false" in the deferred URL and parses back to false. z.number(), z.boolean(), .nullable(),
and z.coerce.boolean() (which reads "false" as true) are type errors and are rejected when
the fragment is created.
Use load for request-only values or to combine forwarded page query into complete props:
// BookingWidget and BOOKING_API_URL are application-specific.
export const BookingWidgetFragment = createFragment({
name: "booking-widget",
component: BookingWidget,
endpoint: {
params: z.object({ hotelId: z.string() }),
forwardPageQuery: z.object({ campaign: z.string().optional() }),
load: async (c, { params, pageQuery }) => ({
hotelId: params.hotelId,
campaign: pageQuery.campaign,
bookingApiUrl: c.env.BOOKING_API_URL,
}),
},
cache: "bookingWidget",
});
load returns all component props; Brix does not merge partial endpoint data, so an endpoint-only
value can never come from a public URL. Inline SSR does not call load because the page already
supplied complete props. Without load, parsed params must be the complete endpoint props.
Configure the endpoint
#Top-level fragment options auth, middleware, enabled, and cache configure the endpoint, like
page-route options; they are siblings of endpoint, not properties inside it. cache: false and
an omitted cache both mean uncached. An authenticated fragment cannot also declare cache: the
combination is a type error and fails at creation, and its responses receive
Cache-Control: private unless it sets its own. Configure server infrastructure as described in
server setup.
The endpoint returns bare HTML: the component wrapped in its fragment root, without a document shell or executable script. Islands inside the fragment carry inert hydration metadata that the assembled page's bootstrap reads; see hydrate fragment islands. A component that is both a fragment and an island renders as a placeholder in a deferred page and as an island inside its own endpoint response.
Fragment responses carry their own browser-visible render-data scope. Islands inside the fragment use
useRenderData during SSR and hydration. The hook does not expose server request context or create a
mutable store. Browser-safe fields are not automatically public-cache-safe; disable caching or use a
private or fully partitioned fragment cache whenever render data is personalized.
Test the endpoint
#The generated test renders the endpoint through the production-configured harness. Once the endpoint declares params, pass them as component prop values; the harness serializes them into the URL exactly as a deferred placeholder would:
import { describe, expect, it } from "brix/test";
import { testFragment } from "#brix/test";
import { SiteHeaderFragment } from "./siteHeader.fragment.ts";
describe("SiteHeaderFragment", () => {
it("renders the fragment", async () => {
const response = await testFragment(SiteHeaderFragment, { params: { transparent: false } });
expect(response.status).toBe(200);
expect(response.html).toContain("Shared header");
});
});
Continue with compose and test fragments.