# Routing > Voltro's file-based router — pages, layouts, render modes, loaders, navigation, islands. The web side of the framework. --- ## Overview _Voltro's file-based router — pages, layouts, render modes, loaders, navigation, islands. The web side of the framework._ The web side of a Voltro app uses **file-based routing**: drop a `page.tsx` file under `src/pages/`, the CLI discovers it on every boot + save, and the file becomes a route. No router config, no manual `` declarations, no codegen step. The suffix is what makes a file a route — the directory tree only decides *which URL*. Anything else under `src/pages/` (components, hooks, tests) is ordinary code and gets no URL, so it can live beside the page that uses it. This section covers everything about how URLs map to React + how Voltro decides when to render, what to ship to the browser, and how to navigate between pages. ## The shape of it ```text src/pages/ ├── layout.tsx # outer shell (wraps every page) ├── error.tsx # error boundary ├── loading.tsx # pending UI ├── not-found.tsx # 404 fallback ├── page.tsx # / ├── about/page.tsx # /about ├── (marketing)/ # route group — no URL segment │ ├── layout.tsx # marketing-scoped layout │ └── pricing/page.tsx # /pricing ├── users/ │ ├── layout.tsx # users-scoped layout │ ├── error.tsx # users-scoped error boundary │ ├── [id]/page.tsx # /users/:id │ └── page.tsx # /users └── docs/ └── [...slug]/page.tsx # /docs/ (catch-all) ``` That's the whole router. No ``, no ``, no `useRoutes`. ## What's in this section - [Pages & dynamic segments](/docs/routing/pages) — file → URL mapping, `[id]`, `[...slug]`, query params - [Layouts & route groups](/docs/routing/layouts) — `layout.tsx`, error boundaries, `(group)/` directories - [Render modes](/docs/routing/render-modes) — `static` vs `ssr` vs `isr`, when to use each - [Loaders & meta](/docs/routing/loaders-and-meta) — server-side data fetch + `` injection - [Navigation](/docs/routing/navigation) — `Link`, `useNavigate`, prefetch on hover - [Islands](/docs/routing/islands) — hydrating only the interactive bits, JS-free pages ## Architecture in one paragraph The framework generates a `.framework/app.tsx` on every boot that imports each `page.tsx` file under `src/pages/` (excluding `node_modules`), wraps them in their layout chains, and produces a `` element. A `mount(App, { group })` call in `.framework/main.tsx` mounts it via `react-dom/client`'s `createRoot` (or `hydrateRoot` for SSR pages). The router watches `window.location` + intercepts `` clicks for client-side nav. You don't write any of this. The CLI regenerates it on every save in dev; the build pipeline freezes it for production. ## Embedding the runtime in a foreign host To mount Voltro's reactive runtime *inside* an app that owns its own routing (a Next.js / Remix / existing React shell), skip the generated boot and use the embeddable provider from the light `@voltro/web/runtime` subpath: ```tsx import { VoltroRuntimeProvider, type MountedApi } from '@voltro/web/runtime' const apis: ReadonlyArray = [ { name: 'app', group, descriptors, wsUrl: 'wss://your-api.example.com/ws' }, ] export const Providers = ({ children }: { children: React.ReactNode }) => ( {children} ) ``` Inside it, every `@voltro/client` hook (`useSubscription`, `useMutation`, `useAction`, …) resolves exactly as in a native Voltro app — it builds + supervises the per-api RpcClient-over-WebSocket + runtime + subscription cache and handles reconnect. `children` render immediately (a pending api reads `undefined` until connected — no spinner gate), so a prerendered host hydrates without a mismatch. The `@voltro/web/runtime` subpath pulls only the rpc/socket/runtime graph, not the router/mount/SSR — keeping the host bundle small. (`FrameworkBoot`, the framework's own web boot, is a thin wrapper over this provider.) Consume the framework as the **published** package — a `file:` link to an unbuilt checkout resolves the raw `src` export, which a foreign bundler can't handle. ## Conventions | Pattern | Behaviour | |---|---| | `index.tsx` in a directory | Maps to the directory's URL (no segment for the filename). | | `[name].tsx` | Dynamic single segment. Available via `useParams<{ name: string }>()`. | | `[...rest].tsx` | Catch-all. `useParams<{ rest: string }>()` joins the captured path with `/`. | | `[[...rest]].tsx` | Optional catch-all. Matches both `/foo` and `/foo/bar/baz`. | | `(name)/` | Route group. Strips the segment from the URL but layouts inside still apply. | | `_*.tsx` | Private — discovery skips it. Useful for helpers next to pages. | | `*.island.tsx` | Hydration island. Bundles as a separate chunk; hydrated only when imported. | ## When NOT to use file-based routing The pattern works for ~99% of apps. Edge cases: - **Programmatically generated routes** — when you can't know the URL ahead of time. Use `[...slug].tsx` + match inside. - **i18n with URL-segment locale** — see [URL strategies](/docs/i18n/url-strategies) for the shipped URL-prefix approach (`/de/docs/foo`). - **Cross-tenant subdomains** — handled at the reverse-proxy layer; the file-based router serves one host's paths. For everything else, drop a file + done. ## Where to next — building the UI inside the page Routing gets you to a page; the **[Schema-driven UI](/docs/ui/overview)** section fills it. It's the other half of the frontend story: - **[Forms & tables](/docs/ui/forms-and-tables)** — `` binds to a mutation, `` to a query; fields + columns come from the descriptors' `effect/Schema`, validation + live auto-optimistic for free. - **[Reactive components](/docs/ui/reactive-components)** — drop-in workflow progress, presence/multiplayer, and AI chat over the durable backend. - **[Client utilities](/docs/ui/client-utilities/use-can)** — the bound-hook toolbox beyond `useSubscription`/`useMutation`: `useCan`, `useDerived`, `usePreview`, `useUndo`, `useProvenance`, `useAsyncValidation`, `useOutbox`, `useWindowedSubscription`, and more. --- ## Pages & dynamic segments _Filesystem → URL mapping, dynamic [id] segments, catch-all [...slug] queries, query params, and private files._ A **page** is any `*.tsx` file under `src/pages/` that's not a special file (`layout.tsx`, `error.tsx`, `loading.tsx`, `not-found.tsx`) and doesn't start with `_`. Its default export is the page component; the URL comes from the file path. ## A static page ```tsx // src/pages/about/page.tsx → /about import type { ReactNode } from 'react' export default function About(): ReactNode { return (

About us

Voltro Cloud is a framework for shipping multi-tenant SaaS.

) } ``` That's it. Save the file, the CLI's discovery sees it on next save, the page is live at `/about`. ## index files `index.tsx` maps to the directory's URL: ```text src/pages/page.tsx → / src/pages/users/page.tsx → /users src/pages/admin/page.tsx → /admin ``` ## Dynamic segments Brackets in the filename are dynamic. The captured value comes through `useParams()`: ```tsx // src/pages/users/[id]/page.tsx → /users/:id import { useParams } from '@voltro/web' export default function User() { const { id } = useParams<{ id: string }>() return

User {id}

} ``` Multiple dynamic segments in one path: ```text src/pages/orgs/[orgId]/projects/[projectId]/page.tsx // → /orgs/:orgId/projects/:projectId const { orgId, projectId } = useParams<{ orgId: string; projectId: string }>() ``` ## Catch-all queries `[...name]` captures one OR more URL segments as a single param value (joined by `/`): ```tsx // src/pages/docs/[...slug]/page.tsx → /docs/ const { slug } = useParams<{ slug: string }>() // /docs/intro/getting-started → slug = "intro/getting-started" ``` **Optional** catch-all (matches the base URL too): ```tsx // src/pages/docs/[[...slug]]/page.tsx // /docs → slug = "" // /docs/foo → slug = "foo" // /docs/foo/bar → slug = "foo/bar" ``` ## Priority When multiple files could match (static, dynamic, catch-all), priority is: 1. Static segments win over dynamic. 2. Dynamic single (`[id]`) wins over catch-all (`[...slug]`). 3. Optional catch-all (`[[...slug]]`) wins over required catch-all (`[...slug]`) — the optional form scores as more specific, so it matches first. ```text src/pages/users/page.tsx # /users → wins for /users src/pages/users/[id]/page.tsx # /users/:id → wins for /users/42 src/pages/users/new/page.tsx # /users/new → wins (static beats dynamic) src/pages/[...rest]/page.tsx # everything else ``` ## Query strings Query params are orthogonal to the URL pattern — they never appear in the file path. A page declares its query contract as a **`searchParams` schema export**, the same page-export convention as `meta`, `loader`, and `renderMode`: ```tsx // src/pages/search/page.tsx import { Schema } from 'effect' import { useSearchParams } from '@voltro/web' export const searchParams = Schema.Struct({ q: Schema.optionalWith(Schema.String, { default: () => '' }), page: Schema.optionalWith(Schema.NumberFromString, { default: () => 1 }), }) export default function SearchPage() { const { q, page } = useSearchParams(searchParams) // q: string · page: number // … } ``` `useSearchParams(searchParams)` — the page passes its **own** export — returns the decoded, typed shape, SSR-aware: the same call site reads the request URL on the server and `window.location.search` on the client. An invalid query string falls back to the schema's defaults instead of crashing the render, so every field must be optional or carry a default (`Schema.optionalWith(..., { default })` — a schema that cannot decode an empty query throws at the first read, naming the fix). Links to the route type-check against the same schema via [typed `withQuery`](/docs/routing/navigation#typed-withquery). Two boundaries worth knowing: - **`renderMode: 'isr'` + a `searchParams` export is refused at boot** — the isr cache is keyed by path (plus tenant + locale), so the first query's variant would be cached and served for every other query. Use `ssr`, or drop the export and read the query client-side only. See [Render modes](/docs/routing/render-modes#isr-incremental-static-regeneration). - **`renderMode: 'static'` build renders see only the schema's defaults** — a build has no query string. The client decodes the live query after hydration; a static page keyed off search params is a client-side concern. ### Mirror routes share ONE schema Bilingual apps with mirrored trees (`pages/x/page.tsx` + `pages/[locale]/x/page.tsx`) re-export the original page's schema instead of copying it: ```tsx // src/pages/[locale]/search/page.tsx export { searchParams } from '../../search/page' ``` One schema, no drift — the mirror page decodes exactly what the original declares. ### Routes without a schema `useSearchParams()` without an argument stays the raw `URLSearchParams` — nothing changes for a route that declares no schema: ```tsx import { useSearchParams } from '@voltro/web' const q = useSearchParams().get('q') ?? '' ``` ## Co-locating components, hooks and tests Only `page.tsx` is a route. Everything else under `src/pages/` is ordinary code and may sit next to the page that uses it: ```text src/pages/ ├── users/ │ ├── page.tsx # → /users │ ├── page.test.tsx # its test │ ├── [id]/page.tsx # → /users/:id │ ├── UserCard.tsx # a component — no URL │ └── useFilters.ts # a hook — no URL ``` No naming trick is needed to keep something out of the router: the absence of the suffix already does it. A `_`-prefixed directory has **no special meaning** — it is neither required nor recognised. > Before this convention, every `.tsx` under `src/pages/` became a route, so a co-located component silently got a URL. That route rendered nothing and nobody visited it in dev; the failure surfaced at the first production build. If you are upgrading, `voltro update` renames your pages for you. ## Two routes, one screen When two URLs must render the same component — a versioned path kept alive because devices in the field are configured against it, say — re-export it instead of copying it: ```tsx // src/pages/v2/page.tsx → /v2, rendering exactly what / renders export { default, renderMode } from '../page' ``` `export { default } from '…'` satisfies the page contract: the module has a default export, it just did not declare it here. Forwarding `renderMode` alongside it is what keeps the two routes from drifting apart — the build follows the forward when it computes the render profile, so `/v2` is classified the same as `/`, not silently as `static`. `export { default as Screen } from '../page'` is the opposite: it renames the default away, leaving this module without one. That still fails the contract. ## Trailing slashes The canonical form is **no trailing slash** — always link with ``, not ``. `Link` forwards every prop it does not consume itself to the underlying ``, `ref` included — so it drops straight into a polymorphic slot (`