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

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

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

`src/features/chrome/components/SiteHeader.tsx`

```tsx
export interface SiteHeaderProps {
  transparent: boolean;
}

export function SiteHeader({ transparent }: SiteHeaderProps) {
  return <header data-transparent={transparent}>Shared header</header>;
}

```

`src/features/chrome/components/siteHeader.fragment.ts`

```ts
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](/docs/fragments-composition.md) 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.

`src/brix.server.ts`

```ts
"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:

`src/features/home/pages/home/Page.tsx`

```tsx
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](/docs/islands.md).

## 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](/docs/pages.md#query-schemas-read-url-strings). 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:

```ts
// 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](/docs/server.md).

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](/docs/fragments-composition.md#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:

`src/features/chrome/components/siteHeader.fragment.test.ts`

```ts
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](/docs/fragments-composition.md).
