Rendering modes
Choose SSG, SSR, ISG, or SPA per route to decide when its HTML is generated and how fresh it stays.
On this page
- Overview
- SSG — static site generation
- Dynamic SSG paths
- SSR — server-side rendering
- ISG — incremental static generation
- Webhook revalidation
- SPA — single page application
- Mixing modes
- Client navigation
- Hydration & useIsHydrated
- Detecting hydration state
- Hydration mismatch warnings
- Checking the build you are about to deploy
Overview
Set render on each route. It defaults to "ssr".
| Mode | HTML generated | Loader runs | Use for |
|---|---|---|---|
ssg |
Build time | Build time | Marketing pages, docs, blogs |
ssr |
Every request | Every request | Personalized, dynamic pages |
isg |
Build + revalidation | Build + on stale | Pricing, catalogs, semi-static |
spa |
Client only | Client navigation | Auth-gated dashboards, admin UI |
SSG — static site generation
route("/about", "./routes/about.tsx", { render: "ssg" });The loader runs once during the build, and the HTML is written to
dist/client/about/index.html and served as a static file.
Dynamic SSG paths
For a route with dynamic segments, export getStaticPaths() and return the
params of each page to build:
export function getStaticPaths(): RouteParams[] {
const posts = getAllPosts();
return posts.map(p => ({ slug: p.slug }));
}
export async function loader({ params }: LoaderArgs) {
return { post: await getPost(params.slug) };
}
export function Component({ data }) {
return <article>{data.post.title}</article>;
}The build renders 10 paths at a time by default (set
pracht({ prerenderConcurrency }) to change it) and writes each page as soon as
it renders, so build memory does not grow with the size of the site.
| Path result | Serverful adapter | Static export |
|---|---|---|
| Redirect or 4xx | Skipped with a warning; rendered live instead | Build fails |
| 5xx | Build fails | Build fails |
| Every path skipped | Build fails | Not applicable |
SSR — server-side rendering
route("/dashboard", "./routes/dashboard.tsx", { render: "ssr" });Every request renders fresh HTML, with the loader's data serialized for hydration. Later client navigations fetch only the loader data as JSON.
Use SSR for pages that depend on the request (cookies, auth, personalization), data that changes on every request, and dynamic pages that need SEO.
ISG — incremental static generation
import { timeRevalidate } from "@pracht/core";
route("/pricing", "./routes/pricing.tsx", {
render: "isg",
revalidate: timeRevalidate(3600), // regenerate at most once an hour
});ISG builds HTML like SSG, then regenerates it after a time window or an
authenticated webhook. Pass an array to use both:
revalidate: [timeRevalidate(3600), webhookRevalidate()].
Node and Cloudflare serve the stale page and regenerate in the background; Netlify and Vercel use their platform caches. Adapters covers each platform.
Webhook revalidation
import { webhookRevalidate } from "@pracht/core";
route("/pricing", "./routes/pricing.tsx", {
render: "isg",
revalidate: webhookRevalidate(),
});Set PRACHT_REVALIDATE_TOKEN, then POST the paths to refresh:
curl -X POST https://example.com/__pracht/revalidate \
-H "Authorization: Bearer $PRACHT_REVALIDATE_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "paths": ["/pricing"] }'The JSON response lists revalidated, skipped, and failed paths, and
scope says how far the refresh reached:
scope |
Adapter | Who sees the new page |
|---|---|---|
global |
Netlify, Vercel | Every visitor |
instance |
Node | Only the server that received the POST, not its replicas |
colo |
Cloudflare | Only the data center that received the POST |
With colo, other data centers render current content on their first uncached
request but keep a copy they already hold, and pracht build warns about each
such route. Add a time window to the route's policy to bound that lag. With
Workers Caching, the webhook purges
the route everywhere and reports global.
SPA — single page application
route("/settings", "./routes/settings.tsx", { render: "spa" });The server does not render the route component. The first document contains the
route's shell and the shell's optional Loading export; the component renders
in the browser once the client router has fetched its route state.
import type { ShellProps } from "@pracht/core";
export function Shell({ children }: ShellProps) {
return <div class="app-shell">{children}</div>;
}
export function Loading() {
return <p>Loading page...</p>;
}Use SPA for auth-gated pages with no SEO needs, complex interactive UIs such as editors, and pages where server rendering adds nothing.
Mixing modes
Modes mix freely in one app and one deployment:
export const app = defineApp({
routes: [
group({ shell: "public" }, [
route("/", "...", { render: "ssg" }), // Static
route("/pricing", "...", {
render: "isg", // Revalidating
revalidate: timeRevalidate(3600),
}),
route("/login", "...", { render: "ssr" }), // Dynamic
]),
group({ shell: "app", middleware: ["auth"] }, [
route("/dashboard", "...", { render: "ssr" }), // Personalized
route("/settings", "...", { render: "spa" }), // Client-only
]),
],
});Client navigation
After the first page load, the client router handles navigation between full-hydration routes of any render mode:
- It matches the new route.
- It fetches the route's loader data as JSON.
- It renders the new route with that data.
- It pushes the URL to browser history.
On a serverful adapter, SSG routes also get fresh loader data during client
navigation; the static HTML serves the first load and crawlers.
Islands routes use full-document navigation unless
client.islandsNavigation swaps them in place.
Hydration & useIsHydrated
SSR, SSG, and ISG pages arrive as rendered HTML, which the browser then
hydrates: Preact attaches event listeners to the existing DOM without
re-rendering it. While a lazy component's code loads during hydration,
Suspense keeps the server-rendered HTML on screen instead of the fallback.
Detecting hydration state
useIsHydrated() returns false during server rendering and the initial
hydration pass, then true once the component has mounted:
import { useIsHydrated } from "@pracht/core";
export function Component({ data }) {
const hydrated = useIsHydrated();
return (
<div>
<h1>{data.title}</h1>
{hydrated && <InteractiveWidget />}
</div>
);
}Hydration finishes once every pending Suspense boundary has resolved.
Components that mount later, such as the next route after a client navigation,
start with true.
Use it to:
- render a placeholder on the server and swap in a client-only widget;
- gate browser-only APIs such as
window.innerWidthorlocalStorage, which would otherwise cause a hydration mismatch; - show a static version first and add interactivity after hydration.
Hydration mismatch warnings
When the server HTML and the client's first render disagree, pracht dev shows
a red banner naming the element or component where Preact stopped. It also
flags a Suspense boundary that resolved during hydration into more or fewer than
one top-level DOM node.
The banner covers full-hydration and islands routes, in development only.
Checking the build you are about to deploy
A production build can render different HTML than dev. To catch mismatches in the output you deploy, keep the reporter in the production bundles:
pracht({ adapter: nodeAdapter(), client: { hydrationWarnings: true } });Build, serve the output, and walk the pages:
pracht build # prints a notice that this build carries diagnostics
pracht previewEach mismatch is logged as a console.error starting with [pracht] and listed
inside #__pracht_hydration_mismatch__ (entries under
[data-pracht-mismatch-list]). A headless browser can assert on either:
const errors: string[] = [];
page.on("console", (message) => {
if (message.type() === "error") errors.push(message.text());
});
await page.goto(url);
expect(errors.filter((text) => text.includes("Hydration mismatch"))).toEqual([]);