Shells

Layouts that wrap routes. The manifest assigns them, so routes can share a shell without sharing a URL prefix.

On this page

Define a shell

Create a module in src/shells/ that exports a Shell component and renders children:

src/shells/app.tsx
import type { ShellProps } from "@pracht/core";

export function Shell({ children }: ShellProps) {
  return (
    <div class="app-layout">
      <nav class="sidebar">
        <a href="/dashboard">Dashboard</a>
        <a href="/settings">Settings</a>
      </nav>
      <main>{children}</main>
    </div>
  );
}

Every other export is optional:

Export Purpose
loader Shell data read with useShellData()
Loading Rendered inside the shell while an SPA route loads
ErrorBoundary Fallback for routes without their own
head Default head metadata
headers Default document headers
serverIslands Server islands the shell renders

Assigning shells

Register shells by name in defineApp, then reference them from routes or groups:

src/routes.ts
export const app = defineApp({
  shells: {
    public: "./shells/public.tsx",
    app: "./shells/app.tsx",
  },
  routes: [
    // Per-route
    route("/", "./routes/home.tsx", { shell: "public" }),

    // Per-group — all children inherit
    group({ shell: "app" }, [
      route("/dashboard", "./routes/dashboard.tsx"),
      route("/settings", "./routes/settings.tsx"),
    ]),
  ],
});

A client navigation between two routes with the same shell keeps the shell mounted and re-renders only the route. A navigation to a route with another shell re-renders the whole tree.

With the pages router, shells come from _app.tsx files instead.

Shell data

Export a loader from a shell to load data every page in it shows, such as the signed-in user, once instead of in every route. Read it with useShellData():

src/shells/app.tsx
import { useShellData, type LoaderArgs, type ShellProps } from "@pracht/core";

export async function loader({ context }: LoaderArgs) {
  return { user: await getUser(context.session) };
}

export function Shell({ children }: ShellProps) {
  const shell = useShellData<typeof loader>();
  return (
    <div class="app-layout">
      <nav class="sidebar">{shell?.user.name}</nav>
      <main>{children}</main>
    </div>
  );
}

Routes inside the shell read the same value. After pracht typegen, pass the shell name to type it; a name the route does not render under throws:

src/routes/dashboard.tsx
export function Component() {
  const shell = useShellData("app");
  return <h1>Welcome back, {shell?.user.name}</h1>;
}

A shell loader gets the same LoaderArgs as a route loader, runs after middleware alongside it, and handles redirect(), notFound(), and errors the same way.

Client navigations within the shell keep its data without running the shell loader again; entering another shell loads that shell's data. useRevalidate(), capability calls, and a <Form> that redirects refresh it.

useShellData() returns undefined when the shell has no loader, in an SPA route's loading state, and in an error boundary shown because the shell loader failed. Islands and hydration: "none" pages get shell data on the server only.

Shell head metadata

Export head from a shell to set site-wide defaults such as the title, icons, and og:site_name. Route head() values override the shell's title and append to its meta and link arrays. See Shell-level defaults for the merge rules and Head metadata for every field.

Shell document headers

Export headers from a shell to add HTTP headers to every page document in it:

src/shells/app.tsx
export function headers() {
  return {
    "content-security-policy": "default-src 'self'",
  };
}

Route headers exports merge with the shell's and win on a name clash. The headers apply to HTML documents, including prerendered SSG and ISG pages, but not to API routes or route-state JSON.

Shell error boundary

Export ErrorBoundary from a shell to render a shared fallback for routes that do not define their own:

src/shells/app.tsx
import type { ErrorBoundaryProps } from "@pracht/core";

export function ErrorBoundary({ error }: ErrorBoundaryProps) {
  return <p>Something went wrong: {error.message}</p>;
}

A route's own ErrorBoundary takes precedence.

The app root

Register an app root with defineApp({ root }) for client infrastructure that must survive a navigation across shells, such as a query cache or a store. The root renders above every shell, on the server and in the browser, and never remounts.

src/routes.ts
export const app = defineApp({
  root: "./root.tsx",
  shells: { app: "./shells/app.tsx" },
  routes: [/* … */],
});

Every export is optional:

src/root.tsx
import { createContext } from "preact";
import type { RootProps } from "@pracht/core";

type Store = { items: Map<string, unknown> };
export const StoreContext = createContext<Store | null>(null);

// Once per server request, before any loader, and once when the browser boots.
export function setup(): Store {
  return { items: new Map() };
}

// Wraps every shell. Must render `children`.
export function Root({ state, children }: RootProps<Store>) {
  return <StoreContext.Provider value={state}>{children}</StoreContext.Provider>;
}

// Server: a JSON snapshot for the browser, or undefined to send nothing.
export function dehydrate(store: Store) {
  return store.items.size > 0 ? Object.fromEntries(store.items) : undefined;
}

// Browser: apply a snapshot, before hydration and on every route-state
// response (navigations, prefetches, revalidations).
export function hydrate(store: Store, snapshot: unknown) {
  for (const [key, value] of Object.entries(snapshot as object)) store.items.set(key, value);
}

Loaders read the request's state as args.root, typed by pracht typegen. What a loader puts into it reaches the browser with the page and with every client navigation; what the server render adds reaches it with the page. @pracht/query is built on this.

Request-dependent data still comes from loaders, and layout data from a shell loader. Islands render without the app root, on the server too, so pass them what they need as props. An app without a root ships none of this code. With the pages router, the root is pages/_root.tsx.