Router overview

File routes, SPA navigation, and optional Oxide SSR for ilha apps.

@ilha/router matches URLs to components. It is a separate package from ilha. Add it when you need more than one page.

Every route is a component. The router matches the URL and mounts the page. Read the current route with useRoute(), head(), and isActive().

Install

npm install @ilha/router

pnpm add @ilha/router

yarn add @ilha/router

bun add @ilha/router

nub add @ilha/router

aube add @ilha/router

Import paths

There is no loader API. Fetch in an async page, or stream from a server module.

Quick start

Client SPA

import { const router: (options?: RouterOptions) => RouterBuilderrouter } from "@ilha/router";

const const HomePage: () => ViewHomePage = () => <JSX.IntrinsicElements.p: HTMLAttributes<HTMLParagraphElement>p>home</JSX.IntrinsicElements.p: HTMLAttributes<HTMLParagraphElement>p>;
const const AboutPage: () => ViewAboutPage = () => <JSX.IntrinsicElements.p: HTMLAttributes<HTMLParagraphElement>p>about</JSX.IntrinsicElements.p: HTMLAttributes<HTMLParagraphElement>p>;
const const NotFound: () => ViewNotFound = () => <JSX.IntrinsicElements.p: HTMLAttributes<HTMLParagraphElement>p>not found</JSX.IntrinsicElements.p: HTMLAttributes<HTMLParagraphElement>p>;

function router(options?: RouterOptions): RouterBuilderrouter()
  .
RouterBuilder.route: (pattern: string, page: Page, opts?: {
    layouts?: LayoutHandler[];
}) => RouterBuilderroute("/", const HomePage: () => ViewHomePage)
  .
RouterBuilder.route: (pattern: string, page: Page, opts?: {
    layouts?: LayoutHandler[];
}) => RouterBuilderroute("/about", const AboutPage: () => ViewAboutPage)
  .
RouterBuilder.route: (pattern: string, page: Page, opts?: {
    layouts?: LayoutHandler[];
}) => RouterBuilderroute("/**", const NotFound: () => ViewNotFound)
  .RouterBuilder.mount: (target: string | Element, options?: MountOptions) => () => voidmount("#app");

File-system routes

import { const pages: (options?: IlhaPagesOptions) => Plugin
Vite plugin — use via `@ilha/router/vite`.pages } from "@ilha/router/vite";
import { function defineConfig(config: UserConfig): UserConfig (+5 overloads)
Type helper to make it easier to use vite.config.ts
accepts a direct 
{@link 
UserConfig
}
 object, or a function that returns it.
The function receives a 
{@link 
ConfigEnv
}
 object.defineConfig } from "vite";

export default function defineConfig(config: UserConfig): UserConfig (+5 overloads)
Type helper to make it easier to use vite.config.ts
accepts a direct 
{@link 
UserConfig
}
 object, or a function that returns it.
The function receives a 
{@link 
ConfigEnv
}
 object.defineConfig({
  UserConfig.plugins?: PluginOption[] | undefined
Array of vite plugins to use.plugins: [function pages(options?: IlhaPagesOptions): Plugin
Vite plugin — use via `@ilha/router/vite`.pages()],
});

Put pages in src/pages/. See File-system routing.

Server HTML

Add Oxide and the SSR middleware when pages or islands run on the server:

import const pages: (options?: IlhaPagesOptions) => Plugin
Vite plugin — use via `@ilha/router/vite`.pages from "@ilha/router/vite";
import const oxide: (options?: OxidejsOptions | undefined) => import("vite").Plugin<any>[] | import("vite").Plugin<any>oxide from "oxidejs/vite";
import { function defineConfig(config: UserConfig): UserConfig (+5 overloads)
Type helper to make it easier to use vite.config.ts
accepts a direct 
{@link 
UserConfig
}
 object, or a function that returns it.
The function receives a 
{@link 
ConfigEnv
}
 object.defineConfig } from "vite";

export default function defineConfig(config: UserConfig): UserConfig (+5 overloads)
Type helper to make it easier to use vite.config.ts
accepts a direct 
{@link 
UserConfig
}
 object, or a function that returns it.
The function receives a 
{@link 
ConfigEnv
}
 object.defineConfig({
  UserConfig.plugins?: PluginOption[] | undefined
Array of vite plugins to use.plugins: [function oxide(options?: OxidejsOptions | undefined): import("vite").Plugin<any>[] | import("vite").Plugin<any>oxide({ 
OxidejsOptions.middleware?: (string | {
    module: string;
    imports?: string[];
})[] | undefined
Module specifiers whose default export is `(request, ctx) => Response | undefined | Promise<Response | undefined>`.
Tried in order at the top of the production fetch handler; a Response short-circuits.
Dev servers use connect middleware instead.middleware: ["@ilha/router/ssr"] }), function pages(options?: IlhaPagesOptions): Plugin
Vite plugin — use via `@ilha/router/vite`.pages()],
});

See Server islands.