Performance

What pracht adds to a page, how it is measured, and the code splitting and preloading you get without configuration.

On this page

What pracht costs a page

Hydration is a per-route setting, so you choose the framework's runtime cost. These are the client JavaScript totals for the same page, rendering the same markup, with one setting changed each time.

Route setting Gzip Raw What reaches the browser
hydration: "none" 0 KB 0 KB Nothing. No script tag is emitted.
hydration: "islands" 8.1 KB 18.1 KB Preact, the island bootstrap, and the island chunks on the page.
hydration: "islands", islands navigation on 11.8 KB 27.9 KB Islands with client: { islandsNavigation: true }.
hydration: "full" 17.4 KB 41.5 KB The above plus the client router: navigation, prefetching, loader fetches.
hydration: "full", prefetching off 15.7 KB 40.5 KB Full hydration with client: { prefetch: false }.
hydration: "full", navigation guards off 17.2 KB 40.7 KB Full hydration with client: { navigationGuards: false }.
hydration: "full", rich data on 17.7 KB 42.2 KB Full hydration with client: { richData: true }.
hydration: "full" + preact/compat 18.1 KB 43.9 KB Full hydration with the React compatibility layer in the graph.

Gzip is a cold load: the route's chunks plus the chunk the router imports after hydration. Raw is the route's chunks only. Both come from bench/baseline.json, measured with Preact 11.0.1 and render-to-string 6.7.0. Your application code sits on top of these.

The settings that move the total:

Setting Effect on gzip
Islands instead of full hydration Removes the whole client router
Prefetching off Saves about 1.6 KB. The router loads the prefetch runtime after hydration, so it counts on a cold load but appears in no route's chunk list
Navigation guards off Saves about 0.25 KB, the full cost of useBlocker()
Accessible navigation off Saves about 0.3 KB; turn it off only if the app moves focus and announces pages itself
Rich data on Costs about 0.3 KB
Islands navigation on Costs about 3.8 KB on islands pages; an islands page without islands then loads about 11 KB instead of nothing

How these numbers are measured

Run the harness from the repository:

Terminal
pnpm bench              # bytes and timings, printed as a table
pnpm bench:check        # bytes only, fails when they drift

The fixture's routes render identical markup and share one interactive component. Only the hydration mode varies, so each delta is framework runtime. preact/compat is measured in a separate app so it does not inflate the other rows.

CI fails when byte sizes move, because they are deterministic. Timings are not, so the harness reports a median and spread and CI does not gate on them.

Measuring your own app

Run pracht build --analyze to print the same report for your app, per route:

Terminal
pracht build --analyze
Route / chunk                        Gzip     Raw
/dashboard (ssr)
  /assets/dashboard-BCIbC3P5.js      744b   1.3kb
  /assets/app-CyBulJul.js            257b    447b
  total (incl. shared)             13.1kb  32.0kb

Add --json for machine-readable output, and set per-route budgets to fail a build when a route ships too much.

Route totals count the chunks a route loads to hydrate. On a full-hydration route, the browser also fetches the prefetch runtime afterwards, about 1.2 KB gzip, which no route total includes.

Route-level code splitting

Each route and shell becomes its own JS chunk, loaded only when needed.

The server knows which route and shell it renders, so it adds <link rel="modulepreload"> hints to <head>. The browser starts downloading the route's chunks before the client entry runs.

HTML
<!-- Injected for the matched route -->
<link rel="modulepreload" href="/assets/home-Bx7kZ3.js" />
<link rel="modulepreload" href="/assets/vendor-D9fK2a.js" />

Browser builds resolve @pracht/core through a client-safe entry, so server-only runtime code stays out of the bundle. The prefetch listeners load after the router starts, off the hydration critical path.

Vendor chunk

Preact and its hooks and compat entry points go into a shared vendor chunk. The browser caches it once for every route, route chunks hold only route code, and deploying a route change does not invalidate the vendor cache.

Composing with your own chunking

Add your own groups under build.rollupOptions.output; pracht adds its Preact group to them in the same form:

vite.config.ts
export default defineConfig({
  plugins: [pracht()],
  build: {
    rollupOptions: {
      output: {
        codeSplitting: {
          groups: [{ name: "editor", test: /src[\\/]features[\\/]editor/ }],
        },
      },
    },
  },
});

Rolldown applies higher priority first, then declaration order. Your groups come first, so at equal priority a group of yours that also matches Preact wins.

After a grouping change, check the prerendered HTML, not just the sizes. A broad group, such as entriesAware over everything, can drop the per-route <link rel="stylesheet"> tags from dist/client/**/index.html. Targeted groups do not.

To place the framework group yourself, turn the automatic one off and spread the exported definition:

vite.config.ts
import { frameworkChunkGroups, pracht } from "@pracht/vite-plugin";

export default defineConfig({
  plugins: [pracht({ vendorChunk: false })],
  build: {
    rollupOptions: {
      output: {
        codeSplitting: {
          groups: [
            ...frameworkChunkGroups(),
            { name: "editor", test: /src[\\/]features[\\/]editor/ },
          ],
        },
      },
    },
  },
});

vendorChunk: false on its own adds no chunking config, which keeps Preact in your app chunks.

CSS per page

Each response links only the CSS for the matched route, its shell, and the islands it rendered. To inline those stylesheets instead, set inlineCss:

vite.config.ts
export default defineConfig({
  plugins: [pracht({ inlineCss: true })],
});

Production HTML then contains <style data-pracht-inline-css> instead of the stylesheet links. It works with both routers, every render and hydration mode, and every built-in adapter. Development keeps links so HMR works.

Inlining saves a render-blocking request but enlarges every HTML response and repeats shared CSS on every page. It inlines whole files, not critical selectors. Choose by how your pages are visited:

Visit pattern Choose
Visitors move between pages (most apps) Link (the default). One cached stylesheet serves the session
Cold, single-page visits (static and content sites from search) Inline. The cache is never reused, and the stylesheet is the request that delays first paint

When a static export's pages each link a small stylesheet, pracht build prints a tip suggesting the flag. Measure both before choosing.

Under a nonce-based CSP, return styleNonce from head() and put the same nonce in style-src. For SSG and ISG pages, prefer linked CSS unless a stable hash policy covers the inline block.

Early hints

A rendered page whose <head> links stylesheets or preloads fonts answers with a Link header listing them. Prerendered SSG and ISG pages carry the same header on the Node, Cloudflare, Vercel, and Netlify adapters. Stylesheets inlined with inlineCss are not listed.

HTTP
Link: </assets/app-D1x9.css>; rel=preload; as=style

On Cloudflare, turn on Early Hints under Speed › Settings › Content Optimization. The CDN caches the header and sends it as a 103 Early Hints response ahead of later requests for the page, so the browser downloads stylesheets and fonts while your loader runs.

Set earlyHints: true on the Node adapter to send the 103 itself, including the page's scripts, once route middleware has passed and before the loaders run:

vite.config.ts
nodeAdapter({ earlyHints: true });

Browsers act on a 103 only over HTTP/2 or HTTP/3, so this helps when an HTTP/2 proxy in front of the server forwards it. It is off by default because some proxies mistake a 103 for the final response.

Real-user Web Vitals

Mount a component in a shared shell to receive CLS, FCP, INP, LCP, and TTFB:

src/components/vitals.tsx
import { useWebVitals } from "@pracht/core";

export function Vitals() {
  useWebVitals((metric) => {
    navigator.sendBeacon(
      "/api/telemetry/vitals",
      JSON.stringify({
        name: metric.name,
        value: metric.value,
        rating: metric.rating,
        id: metric.id,
        path: location.pathname,
      }),
    );
  });
  return null;
}

The hook is SSR-safe and loads its measurement code after mount; apps that never call it ship none. Some metrics arrive only after interaction or on page exit, so send them with sendBeacon() or another unload-safe transport.

Error overlay in dev

When a loader or component throws during SSR in pracht dev, the page shows an error overlay with the message, a source-mapped stack trace, and the failing route ID and file when known. It reloads when you save a fix.

Production builds return standard error responses, or render the route's ErrorBoundary if it exports one.

Defaults

A standard pracht app gets these without configuration:

Optimization What it does
Route code splitting Each route is a separate JS chunk, loaded on demand
Modulepreload hints The browser downloads route JS before the client entry runs
Vendor extraction Preact is cached once, shared across routes
Core runtime splitting Server runtime and prefetch setup stay off the critical path
Per-page CSS Only CSS for the matched route and shell is included
Link preload header CDNs with Early Hints start stylesheet and font downloads before the HTML
Intent prefetching Route data is fetched on hover or focus before the click
Dev error overlay Framework-aware errors that reload when you save a fix