Skip to content
brix.v2.15.0+b120c49

Search documentation

Loading search…

    Documentation menu
    Docs / Pages and UI / HTML fragmentsRead Markdown
    On this page

    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:

    src/features/chrome/components/SiteHeader.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
    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.

    src/brix.server.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
    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:

    src/features/chrome/components/siteHeader.fragment.test.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.