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:
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:
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():
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:
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:
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:
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.
export const app = defineApp({
root: "./root.tsx",
shells: { app: "./shells/app.tsx" },
routes: [/* … */],
});Every export is optional:
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.