`. Renders `` when no route matches.
### `RouterLink`
A declarative link island. Calls `navigate()` on click and prefetches loader data on `mouseenter`.
```ts
RouterLink.toString({ href: "/about", label: "About" });
// → 'About'
```
Opt a specific link out of prefetching with `data-prefetch="false"`.
## File-system routing
`@ilha/router` ships a **pages plugin** (built on [unplugin](https://unplugin.unjs.io/)) that scans `src/pages/`, resolves layout and error boundary chains, and generates a ready-to-use router with zero manual route registration. The same plugin works across bundlers — pick the entry that matches your toolchain:
| Bundler | Import |
| -------- | ----------------------- |
| Vite | `@ilha/router/vite` |
| Rspack | `@ilha/router/rspack` |
| Rolldown | `@ilha/router/rolldown` |
Vite 8+ may use Rolldown under the hood; use `@ilha/router/vite` in `vite.config.ts` either way. Use `@ilha/router/rolldown` when you configure [Rolldown](https://rolldown.rs/) directly (for example with [tsdown](https://tsdown.dev/)).
### Setup
**Vite**
```ts
// vite.config.ts
import { defineConfig } from "vite";
import { pages } from "@ilha/router/vite";
export default defineConfig({
plugins: [pages()],
});
```
**Rspack**
```ts
// rspack.config.ts
import { rspack } from "@rspack/core";
import { pages } from "@ilha/router/rspack";
export default {
plugins: [
pages(),
new rspack.HtmlRspackPlugin({
template: "./index.html",
}),
],
resolve: {
extensions: ["...", ".ts", ".tsx"],
},
module: {
rules: [
{
test: /\.ts$/,
exclude: /node_modules/,
loader: "builtin:swc-loader",
options: {
jsc: {
parser: {
syntax: "typescript",
},
},
},
type: "javascript/auto",
},
{
test: /\.tsx$/,
exclude: /node_modules/,
loader: "builtin:swc-loader",
options: {
jsc: {
parser: {
syntax: "typescript",
tsx: true,
},
transform: {
react: {
runtime: "automatic",
importSource: "ilha",
throwIfNamespace: false,
},
},
},
},
type: "javascript/auto",
},
],
},
};
```
**Rolldown** (tsdown, Rolldown CLI, or other Rolldown-based tools)
```ts
// tsdown.config.ts
import { pages } from "@ilha/router/rolldown";
import { defineConfig } from "tsdown";
export default defineConfig({
entry: ["src/client.ts"],
plugins: [pages()],
});
```
Add `.ilha/` to `.gitignore`.
### Directory structure
```
src/pages/
+layout.tsx ← root layout (wraps all pages)
+error.tsx ← root error boundary
index.tsx → /
about.tsx → /about
(auth)/ ← route group — invisible in the URL
+layout.tsx ← layout scoped to (auth) pages only
sign-in.tsx → /sign-in
sign-up.tsx → /sign-up
user/
+layout.tsx ← nested layout (wraps user/* only)
+error.tsx ← nested error boundary
[id].tsx → /user/:id
[id]/
settings.tsx → /user/:id/settings
[...slug].tsx → /**:slug
```
### Filename → pattern mapping
| File | Pattern |
| -------------------- | ----------- |
| `index.tsx` | `/` |
| `about.tsx` | `/about` |
| `[id].tsx` | `/:id` |
| `user/[id].tsx` | `/user/:id` |
| `[...slug].tsx` | `/**:slug` |
| `(auth)/sign-in.tsx` | `/sign-in` |
### Route groups
Folders wrapped in parentheses — `(name)` — organise files without contributing a URL segment. Use them for shared layouts, co-located pages, or logical grouping with no effect on the URL.
### Layouts
A `+layout.tsx` wraps every page in its directory and all subdirectories. Layouts compose inside-out — nearest layout is innermost. (`.ts` is also supported if you do not need JSX.)
```tsx
// src/pages/+layout.tsx
import { defineLayout } from "@ilha/router";
import ilha, { html } from "ilha";
export default defineLayout((Children) =>
ilha.render(
() => html`
${Children}
`,
),
);
```
### Page loaders
Export a `load` function from any page file. The pages plugin detects it automatically, composes it with any layout loaders, and wires it into the router at SSR time.
```tsx
// src/pages/user/[id].tsx
import { loader } from "@ilha/router";
import ilha from "ilha";
type User = { name: string };
export const load = loader(async ({ params }) => {
const user = await fetchUser(params.id);
return { user };
});
export default ilha
.input<{ user: User }>()
.render(({ input }) =>
{input.user.name}
);
```
### Error boundaries
A `+error.tsx` catches rendering errors for pages in its directory. The nearest boundary wins. If it re-throws, the next outer boundary takes over. (`.ts` is also supported if you do not need JSX.)
```tsx
// src/pages/+error.tsx
import type { ErrorHandler } from "@ilha/router";
import ilha from "ilha";
export default ((err, route) =>
ilha.render(() => (