Loaders & meta

Server-side data fetch via `loader`, page-level `<head>` tags via `meta`, and how the build pipeline runs both.

A loader is the page's data hook. It runs before the React render (during SSR, during SSG, or per-request for ISR/SSR), and its result lands in useLoaderData<T>(). Meta is a sibling export that produces <title> + <meta> tags.

It runs on the server AND again in the browser. A loader is not a server-only hook: it runs during SSR for the first paint, and runs AGAIN, in the browser, on every in-app navigation to the route. Same function, different environment — so anything server-only in it must be guarded with ctx.isServer.

This is the single most expensive thing to learn late, because a client-only failure is invisible to every probe that does not NAVIGATE: a fresh page load, a curl, any SSR check all take the server path and pass. Only clicking a link inside the running app reaches the other one.

Both are static module exports — the framework discovers them, the build pipeline runs them.

A loader

// src/pages/notes/[id]/page.tsx
import { useLoaderData } from '@voltro/web'

interface Note {
  readonly id: string
  readonly title: string
  readonly body: string
}

export const renderMode = 'ssr' as const

export const loader = async ({ params, headers }: {
  params: { id: string }
  headers: Readonly<Record<string, string>>
}): Promise<Note> => {
  // Runs during SSR *and* again in the browser on in-app navigation —
  // guard anything server-only with `ctx.isServer`.
  const res = await fetch(`${INTERNAL_API}/notes/${params.id}`, {
    headers: { cookie: headers.cookie ?? '' },
  })
  if (!res.ok) throw new Error(`note ${params.id}: ${res.status}`)
  return await res.json()
}

export default function NotePage(): ReactNode {
  const note = useLoaderData<Note>()
  return (
    <article>
      <h1>{note.title}</h1>
      <p>{note.body}</p>
    </article>
  )
}

useLoaderData<T>() returns the loader's resolved value, typed via the generic.

On a page that declares a loader, the value is always there. The router never renders such a page without its data: a settled loader commits its data and the displayed route together, a pending one shows the Pending skeleton (or keeps the previous page), and one that threw renders the error subtree. You do not need a guard, and adding one only hides a real mistake behind a ?..

Calling it where no loader exists is an error, and it says so. A level with no loader export throws:

useLoaderData() was called at a level that declares no `loader`. Export `loader`
from this page/layout, or — if this component is shared between routes that have
one and routes that do not — read it with `useOptionalLoaderData()` …

Note what is NOT an absence: an empty result. A loader returning { items: [] } returns exactly that. undefined never means "the query found nothing" — it means "there is no loader at this level".

useOptionalLoaderData() — for a component on both kinds of route

One case needs it: a component genuinely mounted both under routes that declare a loader and routes that do not. It returns undefined instead of throwing.

const data = useOptionalLoaderData<Data>()
const project = data?.project

A loader that legitimately resolves to undefined is not an error — both hooks hand that undefined back. Only the missing loader throws.

When loaders run

renderMode When loader runs
static At voltro build time, once. Result baked into HTML.
ssr Every request.
isr On cache MISS (re-runs when cache stale).

For static pages with getStaticPaths, the loader runs once per enumerated path.

A static loader may finish with throw new RedirectError('/target', { status: 308 }). The build records the pathname, status, and Location instead of emitting HTML; voltro start serves that redirect exactly. Unexpected loader errors still fail the build. If you deploy the generated files behind a static host instead of voltro start, mirror these redirects in that host's routing configuration—the redirect metadata is part of the start bundle, not an HTML file.

Server-rendered data reaches the first client render

For static, ssr and isr pages the framework inlines the loader's result into the HTML document (a <script type="application/json" id="__voltro_state__"> tag) and the browser adopts it before React hydrates. Two consequences worth designing around:

  • useLoaderData() returns real data on the very first client render. It is not undefined until an effect has run, so a page can dereference its loader data directly (data.title) without a guard, and a layout renders its loader's value identically on the server and on the client — no hydration mismatch, no flash of fallback content.
  • The loader does NOT re-run on that initial hydration. It already ran on the server; running it again in the browser would just re-fetch what the page is already showing. If you need work to happen after mount (refreshing data, a side effect), put it in an effect or use useSubscription — do not rely on the loader firing a second time.

SSR first paint, then live — initialSnapshot

When a page wants the SSR-rendered data AND a live subscription, hand the loader's value to useSubscription as its initialSnapshot. The loader fetches the data on the server with ctx.query; the subscription shows that value at the first paint with loading: false — it is real server data, not a placeholder — then swaps to the live stream the instant its first snapshot arrives:

export const loader = async ({ query }) => query('employees.me', {})

export default function Profile() {
  const seed = useLoaderData<Employee>()
  // First paint shows the SSR value; the WS stream takes over seamlessly.
  const { data } = useSubscription<Employee>('app', 'employees.me', {}, { initialSnapshot: seed })
  return <ProfileCard employee={data} />
}

Because the SSR markup and the hydration render read the same loader value, they match — no hydration flicker — and you don't hand-build a seed store to bridge the two. This is distinct from fallback, whose value never came from the server and so keeps loading: true; use exactly one of the two.

Seed whatever the screen checks FIRST, not whatever is most interesting. A component's server render stops at its OUTERMOST unsatisfied gate, so an unseeded subscription in an early branch hides every seeded one below it:

// Seeding `roadmap` changes nothing while this branch is the first one.
if (availableYearsIdle || availableYearsLoading) return <Spinner />
return <Roadmap data={roadmap} />

The symptom is a page that still server-renders a spinner after you seeded the data you care about. Walk the component's early returns from the top and seed each subscription they read, or move the gate below the render you want. The same applies to an auth gate: a useSubscription-backed AuthenticationProvider has no data during a server render, so every page under it renders its loading state until that subscription is seeded too.

Client-side navigation is unchanged: moving to another route runs that route's loaders in the browser as usual. A spa page has no server render, so its loader runs on the client on first mount.

Layout loaders are inlined the same way, keyed per layout, so each layout reads its OWN data on the first render. This includes voltro build's static prerender: it runs the page loader and every layout loader in the chain at build time, so a CMS-backed nav or footer is baked into the prerendered file and the layout loader does not re-run after hydration. Layout loaders see the same build-time context the page loader does — params, pathname, signal — and nothing request-shaped: there is no headers and no query at build time. A layout loader that needs either belongs on an ssr page.

If a layout loader throws during the build, the page is still prerendered — with no layout data, and a warning in the build log. The layout then resolves its data on the client after mount, and the PAGE keeps its own inlined data for the whole of that window, so the no-guard promise above still holds: only the layout shows its no-data fallback until its loader settles.

Deferring slow data: defer() + <Await>

A loader blocks the whole response. One slow field therefore costs every byte of the page — the user stares at nothing while a report query runs. defer() splits the loader's result into data that blocks the shell and data that streams in after it, behind a <Suspense> boundary the server flushes as soon as the promise settles.

// src/pages/dashboard/page.tsx
import { Await, defer, useLoaderData } from '@voltro/web'

export const renderMode = 'ssr' as const   // required — see below

export const loader = async ({ query }: { query?: <T>(tag: string, input?: Record<string, unknown>) => Promise<T> }) => defer(
  // EAGER — awaited before the shell renders. Keep this fast.
  { user: await query?.<User>('users.me') },
  // DEFERRED — NOT awaited. Each becomes a promise on useLoaderData().
  { report: query!<QuarterlyReport>('reports.quarterly') },
)

export default function Dashboard() {
  const { user, report } = useLoaderData<Awaited<ReturnType<typeof loader>>>()
  return (
    <main>
      <h1>Hello {user?.name}</h1>

      <Await value={report} fallback={<ReportSkeleton />}>
        {(report) => <ReportTable rows={report.rows} />}
      </Await>
    </main>
  )
}

What the browser sees: the full page with <ReportSkeleton /> in place, immediately — then the real table, injected in a later chunk of the same response. No second request, no client-side fetch, no loading spinner driven by useEffect.

Two explicit buckets, not one object. defer(eager, deferred) takes them separately rather than treating any promise-valued field as deferred. Deferral is then something you wrote down, not something inferred from a value's runtime shape — and useLoaderData() can type it: eager fields come back as values, deferred fields as Promise<T>, so the compiler tells you which ones need an <Await>.

<Await>

Prop Meaning
value A deferred field off useLoaderData().
fallback Rendered until the value arrives. This is what ships in the streamed shell — keep it cheap and layout-stable.
children (value) => ReactNode — rendered with the resolved value.
errorFallback Rendered if the deferred promise rejects. Without it, a rejection renders nothing in that subtree.

<Await> owns the <Suspense> boundary and the hydration handoff for the streamed value. Do not hand-roll it with <Suspense> + use() — the server and the client would then have to agree on a wire format that the framework otherwise guarantees by construction.

A rejected deferred value never takes the page down: it renders errorFallback in place, on the server and on the client alike.

The registry handoff script is retained during SSR and hydration, then removed. Client recovery and hot updates reuse the settled value without creating a new executable script; this keeps React 19.3 streaming free of script warnings.

defer() requires a streamed response and full interactivity

That means renderMode: 'ssr', or — for a layout loader — the SSR layout shell of a renderMode: 'spa' page under it, which voltro dev and voltro serve also stream (see render modes). Every other combination is a hard error at boot or build, naming the page — because each one fails silently otherwise:

Combination Why it is rejected
renderMode: 'static' The static prerender uses renderToString, which does not support Suspense. It emits an errored boundary and a "switched to client rendering" template with no warning — the artefact would ship a permanent fallback.
renderMode: 'isr' ISR caches a completed HTML string. Filling it in would make defer() a silent no-op that still reads like it streams.
interactive: 'none' Revealing a streamed boundary needs React's inline reveal scripts, and this mode ships no JS. The fallback would be permanent.
interactive: 'islands' The page's React root never hydrates, so nothing consumes the streamed value.
A prerendered spa layout shell voltro build writes it to a file, which has no "after". Unreachable in practice — the build only prerenders a shell whose chain has no layout loader — but refused by name if it ever is reached.

In all of these the fix is the same: put the value in the eager bucket (or return it directly) and let the page render as it did before.

Layout loaders can defer too

A layout.tsx loader may return defer() under the same rules. Its deferred fields are keyed per layout, so a layout reads its own promises via useLoaderData() exactly as a page does.

This includes a layout that wraps a client-only (renderMode: 'spa') page. The server renders that route as a layout shell — the layout chain around an empty page slot — and a deferring layout makes that shell stream: chain and slot first, the deferred layout value afterwards. The page still mounts on the client after hydration, unchanged. What a spa page's own loader cannot do is defer: it runs in the browser, so there is no server render to stream into.

Client-side navigation

On a client-side navigation there is no server render, so the loader runs in the browser and its deferred fields are ordinary promises. <Await> renders the fallback and swaps in the content when they settle — the same code, driven by React alone.

Loader arguments

export const loader = async (ctx: {
  readonly params:   Readonly<Record<string, string>>  // URL params from [name] segments
  readonly pathname: string                             // matched path (no query string)
  readonly isServer: boolean                            // true during SSR/SSG, false in the browser
  readonly search:   string                             // raw query string incl. `?`, or '' — filled on every path
  readonly signal:   AbortSignal                        // Aborts if the client disconnects mid-render, or a newer navigation replaces this one
  readonly headers?: Readonly<Record<string, string>>  // Request headers (SSR/ISR only — empty for SSG/client)
  // Call the backend rpc directly — on the server AND in the browser;
  // `undefined` only in an app with no api. Resolves a query's FIRST
  // (initial) snapshot.
  readonly query?: <T = unknown>(tag: string, input?: Record<string, unknown>) => Promise<T>
}) => Promise<unknown>

Branch on isServer, not on what happens to be missing

isServer is the supported way to ask which invocation this is. The two things that look like they answer the same question do not:

  • query is present on both paths, so if (ctx.query) cannot tell them apart. It was once absent in the browser, and code that branched on its ABSENCE broke the day that changed; the absence of a function never said why it was absent.
  • headers is {} in the browser, not undefined — so if (ctx.headers) is TRUE on both paths. A deployment wrote exactly that check and it silently did nothing.
export const loader = async (ctx: LoaderContext) => {
  if (ctx.isServer) seedStore(prefs, await ctx.query!('prefs.get'))
  return null
}

The loader context carries pathname and search, not a request object.

pathname is deliberately query-free — a loader keyed on ?tab=2 would cache badly. search carries the raw query string (with its leading ?, or ''), filled identically on client navigation, voltro dev SSR and voltro start SSR. Parse it with new URLSearchParams(ctx.search).

Reach for search when the loader makes a decision, not when it fetches data. The case it exists for is a redirect target that depends on a parameter:

import { RedirectError } from '@voltro/web'

export const loader = async (ctx) => {
  const player = await ctx.query('players.byCode', { code: ctx.params['playerCode'] })
  if (!player) {
    // Preserve kiosk mode across the redirect — otherwise a kiosk terminal
    // drops back to normal mode after every failed scan.
    const mode = new URLSearchParams(ctx.search).get('mode')
    throw new RedirectError(`/?error=${ctx.params['playerCode']}${mode ? `&mode=${mode}` : ''}`)
  }
  return { player }
}

Do not reconstruct this from window.location.search: that exists only on the client-navigation path, so a fresh SSR request loses the value — which is the bug the field was added to remove.

Use signal for any fetch that could outlive the request — pass it to fetch(url, { signal }) so cancelled requests don't waste CPU.

Fetching backend data with ctx.query

Instead of hand-rolling a fetch(INTERNAL_API/...), a loader can call the backend rpc directly through ctx.query — the same query tags the client subscribes to, resolved to their initial snapshot. It works on both paths: the server calls it for a fresh load, the browser for a click inside the app:

// src/pages/notes/[id]/page.tsx
import { useSubscription } from '@voltro/client'
import { useLoaderData, type PageMeta } from '@voltro/web'

interface Note { readonly id: string; readonly title: string; readonly body: string }

export const renderMode = 'ssr' as const

export const loader = async ({ params, query }: {
  params: { id: string }
  query?: <T>(tag: string, input?: Record<string, unknown>) => Promise<T>
}) => {
  // `query` is undefined only in an app with no api. SSR forwards the
  // request's cookie, so the api resolves the SAME Subject + tenant
  // as the WebSocket path; the browser reads over that WebSocket.
  const note = query ? await query<Note>('notes.get', { id: params.id }) : undefined
  return { note }
}

export const meta = ({ loaderData }: { loaderData: { note?: Note } }): PageMeta => ({
  title:       loaderData.note ? `${loaderData.note.title} — Notes` : 'Notes',
  description: loaderData.note?.body.slice(0, 140) ?? '',
})

export default function NotePage() {
  const { note: ssrNote } = useLoaderData<{ note?: Note }>()
  // Live updates after hydration: useSubscription takes over from the
  // SSR snapshot. The loader gave us first-paint HTML + correct meta;
  // the subscription keeps it fresh.
  const { data } = useSubscription<Note>('app', 'notes.get', { id: ssrNote?.id ?? '' }, { skip: !ssrNote })
  const note = data ?? ssrNote
  if (!note) return null
  return <article><h1>{note.title}</h1><p>{note.body}</p></article>
}

Browser loaders use this query seam in workspace development and in npm-installed applications. The cross-package adapter ships the declarations required by the web router.

Two rules that fall out of this:

  • query runs on both paths, and reads once. A client navigation re-runs the loader in the browser, and query is there too, so a meta built from the loader titles a clicked-to page exactly as a fresh load of the same URL. It is a read, not a subscription: for data that must stay live after hydration, use useSubscription in the component.
  • A refusal rejects with the declared error itself. A guard's ScopeError, a query's declared error, a failed call's typed error — query rejects with that value on both paths, the same one a hook's error holds, so errorTag(err) reads its tag. See Loader errors.
  • It is the visitor's session on both paths. On the server it forwards the request cookie, so the HTTP rpc resolves the same Subject + tenant as the WebSocket connection would and tenant-scoped queries return the right rows during SSR. In the browser it goes over that WebSocket connection itself.

Under the hood, on the server ctx.query is a one-shot POST /rpc call (see Wire protocol). In the browser it takes the first event of the same rpc over the page's WebSocket and closes it, or closes it earlier when a newer navigation replaces this one (signal).

Use the loader's ctx.query for these reads. The web router supplies the transport integration; application loaders do not import its client helpers directly.

Authentication in loaders

Auth is resolved by the api, never the web app. Two rules follow:

  • Strategies live on the type:'api' app. A type:'web' app has no auth middleware, so auth.strategies in a web app.config.ts does nothing. Configure your IdP (supabaseStrategy, workosStrategy, the built-in password strategy, …) on the api's app.config.ts.
  • ctx.query forwards the request's cookie automatically. A server-side loader's ctx.query sends the browser's Cookie header on the one-shot POST /rpc, so the api resolves the SAME Subject + tenant it would over the WebSocket. You never thread a token through by hand — a logged-in user's cookie-mode session (e.g. @supabase/ssr's sb-<ref>-auth-token) is verified by the api's strategies, and tenant-scoped queries return that user's rows during SSR.

So a cookie-mode Supabase app configures supabaseStrategy({ cookieName: 'sb-<ref>-auth-token' }) on the api; the web loader's ctx.query then authenticates for free. See Supabase Auth.

ctx.query also tells the api who the visitor is: it carries the visitor's address as x-forwarded-for, which the api believes once it trusts the web tier. Without that, per-IP rate limits count every visitor against the web server. See Server-rendered pages call the api on the visitor's behalf.

Renewing an EXPIRED session — middleware.ts

The rules above assume the cookie is still valid. When it is not — a token older than the IdP's lifetime, which for a 1-hour token is practically every first page view of the day — the api resolves the caller to anonymous and every loader and preload on the page fails.

You cannot fix that in a loader. ctx.query and every preload entry are bound from ONE cookie string before any loader runs, so a layout loader that renews the session cannot reach them. middleware.ts at the web app root runs earlier than both, says which routes it covers, and writes the rotated cookie back so this render and the browser agree.

See Middleware for the full contract: match (under / routes / except / assets), the one-middleware-per-route rule, and what it deliberately cannot do.

Errors from loaders

A loader ends in one of three ways: it returns data, it throws a control signal (notFound() / redirect()), or it throws anything else.

A thrown error. On a client-side navigation the router renders the nearest error.tsx with it: for a page loader inside every layout (each keeps its data), for a layout loader in that layout's place, inside the layouts above it. On a server render (a first request or a reload) the same throw answers 500: voltro dev puts the error text in the body, voltro start answers server error and reports the error to the configured error reporter. error.tsx is not rendered on the server for a loader failure.

A redirect (redirect('/login'), or throw new RedirectError(...)) answers 303 + Location on the server (307 / 308 when you pass that status) and replaces the history entry on a client navigation. When several loaders of one request fail, the OUTERMOST decides, whatever order they finished in: a root layout's redirect() beats a nested layout's notFound().

For 404s, throw a NotFoundError:

import { NotFoundError } from '@voltro/web'

export const loader = async ({ params, query }) => {
  const note = query ? await query('notes.get', { id: params.id }) : undefined
  if (!note) throw new NotFoundError(`note ${params.id}`)
  return note
}

The framework answers 404 and renders the nearest not-found.tsx for the URL — the same file an unmatched URL under that path gets: the deepest directory with a not-found.tsx whose URL prefix owns the pathname. A dynamic segment owns any value (teams/[teamId]/not-found.tsx answers /teams/team_01/daily), a route group adds no segment, and at equal depth a static segment beats a dynamic one.

It renders inside that directory's layouts, minus the layout whose loader threw and every layout below it — that layout has no data to render with. The layouts above render with their own loader data:

Who called notFound() Layouts around the not-found
A page loader every layout of the not-found's directory, each with its data
A layout loader only the layouts above that layout
A layout around the not-found itself (an unmatched URL under it, for example) the chain is cut there as well

So a (dashboard)/teams/[teamId]/layout.tsx whose loader calls notFound('team …'), with a not-found.tsx beside it, answers the team's not-found.tsx inside the root layout and the (dashboard) layout — without the team layout. A client-side navigation to the same URL shows the same boundary, and the 404 document hydrates into it, so its links keep working. Only an app with no not-found.tsx owning the path gets a plain-text not found (on a client navigation, the router's built-in 404 card).

The notFound() helper is throwing sugar for the same thing — const note = (await load()) ?? notFound('note ' + params.id) reads well when the not-found is inline.

For something that existed and was removed on purpose — a page taken down, an account closed — gone() answers 410 Gone instead of 404. It renders the same not-found.tsx; only the status differs, and a search engine drops a 410 address instead of asking again. new NotFoundError(detail, { gone: true }) is the same thing; error.status is 404 or 410.

import { gone } from '@voltro/web'

if (note.deletedAt !== null) gone(`note ${params.id}`)   // 410 + the same not-found.tsx

Meta

import type { PageMeta } from '@voltro/web'

export const meta: PageMeta = {
  title:       'Notes — Voltro',
  description: 'All your notes, in one place.',
  tags: [
    { property: 'og:title',        content: 'Voltro Notes' },
    { property: 'og:description',  content: 'All your notes, in one place.' },
    { property: 'og:image',        content: '/og.svg' },
    { name:     'twitter:card',    content: 'summary_large_image' },
  ],
}

The framework injects these into the HTML's <head> at build / SSR time:

<head>
  <title>Notes — Voltro</title>
  <meta name="description" content="All your notes, in one place." />
  <meta property="og:title" content="Voltro Notes" />
  <meta property="og:image" content="/og.svg" />
  …
</head>

The default document title

A page's meta.title replaces the generated shell title — in development and production, in buffered SPA layout shells and ISR alike: there is exactly one <title> in the document, never the shell's beside the page's. The same holds for a <meta> the page sets by name or property (description, theme-color, a PWA tag): the page's replaces the shell's. Before any page sets one — the initial HTML shell, a route with no meta, an error page — the browser tab shows the app's default title, set in app.config.ts:

export default {
  type: 'web' as const,
  name:  'AcmeDashboard',   // internal identifier (package/port lookup) — PascalCase by convention
  title: 'Acme',            // human document title baked into the HTML shell
}

title is the default <title>. It is distinct from name, the app's internal identifier — leaking that PascalCase identifier into the tab reads as a dev artefact. When title is unset the shell falls back to name, so set a real product title on any app users actually see. Per-page meta.title still wins wherever a page provides one.

Dynamic meta from params + loader data + locale

When the meta depends on the URL or on what the loader fetched, export meta as a function. It receives a single object { params, loaderData, locale } and runs at build / SSR time after the loader resolves:

export const meta = ({ params }: { params: { id: string } }): PageMeta => ({
  title: `Note ${params.id} — Voltro`,
  description: '…',
})

Reading the loader's result lets the title/description reflect fetched fields — the canonical "page title is the note's title" case:

export const loader = async ({ params, query }) => ({
  note: query ? await query('notes.get', { id: params.id }) : undefined,
})

export const meta = ({ loaderData }: { loaderData: { note?: { title: string; body: string } } }): PageMeta => ({
  title:       loaderData.note ? `${loaderData.note.title} — Voltro` : 'Voltro',
  description: loaderData.note?.body.slice(0, 140) ?? '',
})

The third context field — locale: string — is the active i18n locale for this render. For [locale]/… routes it carries the URL-prefix locale ('de' on /de/notes/42). For bare-path routes it carries the active locale from the framework's voltro:locale cookie when set — so cookie-based i18n works too (an authed dashboard with no [locale] URL still gets a translated <title> that tracks the language switch). Without the cookie it is the locale the server resolved for this request: Accept-Language, else the app's defaultLocale. In the browser, meta reads that same answer from <html lang>, which the server stamps on every document it renders, so a first visit keeps the language it was rendered in after hydration. Use it to localise title / description / canonical / OG per locale at SSG time so search engines see translated head tags on every variant, and to give cookie-i18n pages a translated tab title:

import { getCatalog } from '../lib/locale'
import { seoAlternates } from '@voltro/web'

export const meta = ({ locale }: { locale: string }): PageMeta => {
  const c = getCatalog(locale)
  return {
    title:       c['seo.notes.title']       as string,
    description: c['seo.notes.description'] as string,
    // Canonical URL for THIS locale + a reciprocal `hreflang` alternate for
    // every locale (incl. `x-default`), spread straight into the meta.
    ...seoAlternates({
      siteUrl:       'https://notes.example.com',
      path:          '/notes',
      locale,
      locales:       ['en', 'de'],
      defaultLocale: 'en',
    }),
  }
}

meta(ctx) runs once per (page × locale) at build time. The full per-locale SSG flow — [locale]/… mirror routes, the build-time <I18nProvider> wrap, and the dist layout — is documented in Internationalization → URL strategies.

loaderData is the PAGE loader's result. Because meta runs server-side after the loader, the SSR'd <head> is already correct on first paint — no client-side title patching, no flash. After a click inside the app the loader runs again in the browser, with ctx.query there too, so meta gets the same data and the page gets the same title as a fresh load of its URL.

Technical SEO: canonical, hreflang, sitemap & robots

The framework ships the cheap technical-SEO primitives so an indexable app gets them without app-level plumbing.

Canonical + hreflang helpers (@voltro/web) are pure functions you call from meta. They are browser-safe, so importing them into a *.page.tsx never drags a server module into the client bundle:

  • canonicalUrl(siteUrl, path) — one absolute canonical URL.
  • seoAlternates({ siteUrl, path, locale, locales, defaultLocale }) — returns { canonical, links } where canonical is this locale's URL and links is one rel="alternate" per locale (each an absolute URL, as Google requires) plus hreflang="x-default". The alternate set is reciprocal across every locale — exactly what Google's hreflang rules want. The locale model is URL-PREFIX routing: the default locale on the bare path (/notes), other locales prefixed (/de/notes).

Keeping a page out of the index — set noIndex on its meta. It emits <meta name="robots" content="noindex, nofollow"> AND excludes the route from the generated sitemap.xml:

export const meta: PageMeta = { title: 'Checkout', noIndex: true }

sitemap.xml + robots.txt are generated at voltro build from the prerendered routes. Turn them on with a seo.siteUrl in app.config.ts:

export default {
  type: 'web' as const,
  name:  'Notes',
  locales: ['en', 'de'],
  defaultLocale: 'en',
  seo: {
    siteUrl:  'https://notes.example.com',
    disallow: ['/admin'],           // extra robots Disallow prefixes (optional)
  },
}
  • sitemap.xml lists every prerendered route (minus noIndex ones). With 2+ locales, each URL carries the full xhtml:link alternate set. Written only when seo.siteUrl is set — absolute URLs are required.
  • robots.txt is generated even without siteUrl. Production allows all and advertises the sitemap; voltro dev — and any build with VOLTRO_SEO_NOINDEX=1 (staging / preview deploys) — disallows everything, so a non-production surface never gets indexed by default.
  • A sitemap another app serves — an api route this web app proxies, say — is seo: { siteUrl, sitemap: 'external' }: the build writes no sitemap.xml (nothing shadows the proxied one), and the production robots.txt still names <siteUrl>/sitemap.xml.
  • A user-authored public/sitemap.xml / public/robots.txt always wins — the generator never overwrites one.

Examples

// src/pages/dashboard/page.tsx
import { useLoaderData } from '@voltro/web'

export const renderMode = 'ssr' as const

export const loader = async ({ headers }) => {
  const cookieHeader = headers.cookie ?? ''
  const me = await fetch(`${INTERNAL_API}/auth/me`, { headers: { cookie: cookieHeader } })
  if (!me.ok) throw new RedirectError('/login')
  const user = await me.json()
  return { user }
}

export default function Dashboard() {
  const { user } = useLoaderData<{ user: User }>()
  return <h1>Hi {user.name}</h1>
}

RedirectError is the framework's way to issue a 303 from a loader. See Navigation for client-side analog.

SSG with per-post meta

getStaticPaths has no framework store — it reads its own content source (a CMS client, the filesystem, an API). The loader of a static page runs at build time, where there is no query, so it reads the same source:

// src/pages/blog/[slug]/page.tsx
import { getPost, listPostSlugs, type Post } from '../../content/posts'

export const renderMode = 'static' as const

export const getStaticPaths = async () => {
  const slugs = await listPostSlugs()              // your own content source — fs / CMS / API
  return slugs.map((slug) => ({ params: { slug } }))
}

export const loader = async ({ params }) => {
  // The same content source as `getStaticPaths`: at build time there is no
  // `query` — no request, and no api session to call it with.
  return { post: await getPost(params.slug) }
}

export const meta = ({ loaderData }: { loaderData: { post: Post } }): PageMeta => ({
  title:       `${loaderData.post.title} — Blog`,
  description: loaderData.post.excerpt,
})

Loaders are NOT React hooks

They're plain async functions. They can't call useSubscription, useState, etc. — they run outside React: on the server (or at build time) for a fresh load, and in the browser for a client navigation.

If you need a reactive query (live updates), use useSubscription in the component AFTER hydration; for the initial render's data, use the loader.

OG images from a template — ogImage

Declare the page's og:image as a satori JSX template and the framework produces the PNG: at BUILD time for static pages (hashed into dist/assets/og/, tags injected with the absolute seo.siteUrl), ON DEMAND for ssr pages over a signed route with a cache.

export const ogImage = ({ params, loaderData, locale }: {
  params: Record<string, string>
  loaderData: unknown
  locale: string
}) => ({
  type: 'div',
  props: {
    style: {
      display: 'flex', width: '100%', height: '100%',
      background: '#0b1220', color: '#fff', fontSize: 72, fontFamily: 'Inter',
      alignItems: 'center', justifyContent: 'center',
    },
    children: `My post ${params['slug'] ?? ''} (${locale})`,
  },
})

meta wiring is automatic: og:image, twitter:image and twitter:card land in the head — unless your meta already sets og:image, which then wins (no duplicate tag for crawlers to pick at random).

Preconditions, decided rather than improvised:

  • A declared font is REQUIRED (Fonts) — satori cannot render text without a font buffer, and there is no bundled default (that would ship a license artifact). Missing font → a named build/boot error with the fix. The renderer uses the ORIGINAL un-subsetted files, so glyphs outside your declared subsets still render.
  • ssr pages need VOLTRO_OG_SECRET in multi-replica deploys. The render signs the on-demand URL (HMAC over route + params + tenant + locale; tampering answers 403) and a per-boot minted secret only verifies in the process that signed it — behind a load balancer set the env var (same value on every replica), or the deploy boot refuses, loudly. Images are cached in the same backend as the page cache; tenant and locale are part of the key wherever the template uses them.
  • Emoji are not supported — satori renders them only via a per-glyph CDN fetch, which collides with the no-external-requests posture. Use an image in the template instead: a ?image import's blurDataURL/src, or any data-URI (src: \data:image/png;base64,…`) inside an img` element of the template — the standard avatar/logo card works that way.

Anti-patterns

  • Calling ctx.ai.generate(...) in a loader without timeouts. Loaders shouldn't take >2s. For slow data, render a Suspense fallback + useSubscription after hydration.
  • Loaders that mutate state. Loaders are reads — they're cached, retried, run at build time. Use mutations for writes.
  • Hardcoding env-only secrets in meta tags. meta ships to the client. Public meta only.