The Route Table#

Declare every URL in your app in one place: src/routes.ts. A code-defined route table makes URL redesign a one-edit refactor and keeps URL structure independent of file layout, with no filesystem-based discovery to work around.

Why one file#

A code-defined route table makes URL design a one-edit refactor (rename a path, move a leaf), keeps URL structure independent of file layout (organize files by domain, not by URL), and gives agents and devtools a single source of truth they can grep. The trade you make is a manual entry per route.

A complete example#

// src/routes.ts
import { defineRoutes } from 'hono-preact';

export default defineRoutes([
  { path: '/', view: () => import('./pages/home.js') },
  { path: '/demo/login', view: () => import('./pages/demo-login.js') },
  {
    path: '/demo/projects',
    layout: () => import('./pages/projects-layout.js'),
    children: [
      {
        path: '',
        view: () => import('./pages/projects-list.js'),
        server: () => import('./pages/projects-list.server.js'),
      },
      {
        path: ':projectId/issues/:issueId',
        view: () => import('./pages/issue.js'),
        server: () => import('./pages/issue.server.js'),
      },
    ],
  },
  {
    path: '/demo/projects/:projectId',
    view: () => import('./pages/project.js'),
    server: () => import('./pages/project.server.js'),
  },
  { path: '*', view: () => import('./pages/not-found.js') },
]);

That table covers four URL behaviours:

Route entry fields#

The three valid shapes#

defineRoutes validates the tree at runtime and throws with the offending URL if the shape is wrong: view + layout, view + children, layout without children, child path starting with /, or a route declaring none of view/layout/children.

Mounting#

You do not write iso.tsx or server.tsx. The framework generates both as virtual modules from your routes.ts and Layout.tsx. The client entry hydrates <Routes> inside <LocationProvider>; the server entry calls createServerEntry, which builds the loaders RPC, the page-action POST handler, the realtime socket upgrade, your optional api.ts, and the SSR catch-all on one Hono app and exports it as the worker's default. See Project Structure for the file layout the plugin assumes.

If you need to customize the client or server entry (rare), pass a path override via the Vite plugin's clientEntry / entry options and follow the patterns in the generated virtual modules.

Inline imports stay inline#

Every view, layout, and server is () => import('./path'). The arrow shape is required for code-splitting: bundlers create a separate chunk per import() call site. A helper that takes a string (view: lazy('./pages/home')) would either lose splitting or require a transform plugin. The five characters of () => per route is the trade for zero magic and full bundler support.

Sharing references for non-layout routes#

When two leaves point at the same component (e.g. mounting one page at multiple paths), hoist the import thunk to a const so the framework's lazy() memoization sees the same identity and produces one shared component reference:

const sharedView = () => import('./pages/shared.js');

defineRoutes([
  // ...
  { path: '/a', view: sharedView },
  { path: '/b', view: sharedView },
]);

For layout groups, identity sharing is automatic: a layout group is registered at both /path and /path/* with the same component reference, so intra-group navigation does not remount the layout. See Layouts & Nested Routes for the full pattern.

What defineRoutes returns#

type RoutesManifest = {
  tree: ReadonlyArray<RouteDef>; // the original input, for introspection
  flat: ReadonlyArray<FlatRoute>; // the registered routes
  serverImports: ReadonlyArray<
    // every `server` thunk in the tree
    () => Promise<unknown>
  >;
  serverRoutes: ReadonlyArray<ServerRoute>; // server-bound nodes (loaders/actions/rooms/sockets)
  routeUse: ReadonlyArray<{
    path: string;
    use: ReadonlyArray<Middleware | StreamObserver>;
  }>; // page-layer `use` chain per node
};

tree is the original input retained for devtools and dev-time introspection. flat is what <Routes> registers with preact-iso. serverImports is what the generated server entry (through createServerEntry) adapts into the loader and action handler map. serverRoutes and routeUse are the introspection surfaces the page-action resolver and the page-layer use resolver read, so the render gate and the data gate cannot drift.

Page-layer middleware on a route node#

A route entry can carry a use field to attach page-layer middleware to that node and all its descendants. The guard applies to the node's own view render (SSR and client navigation) and to every loader and action RPC under that subtree, so the render gate and the data gate cannot drift.

import { defineRoutes } from 'hono-preact';
import { requireSession } from './auth/session.js';

export default defineRoutes([
  { path: '/login', view: () => import('./pages/login.js') }, // ungated
  {
    path: '/dashboard',
    use: [requireSession], // gates everything below
    children: [
      {
        path: '',
        view: () => import('./pages/dashboard.js'),
        server: () => import('./pages/dashboard.server.js'),
      },
      {
        path: 'settings',
        view: () => import('./pages/settings.js'),
        server: () => import('./pages/settings.server.js'),
      },
    ],
  },
]);

use takes an array of middleware. When multiple ancestors each carry use, they compose outer-to-inner in tree order (outermost ancestor first). A sibling that is not a descendant of the guarded node is not affected.

For the full chain model and middleware authoring, see Middleware.

See also#

• Layouts & Nested Routes: the layout field, LayoutProps, identity preservation, the inner-router lowering.
• Adding Pages: the page-authoring side: views, server bindings, definePage.
• Server Loaders: what the server import contains.
• Middleware: the full middleware chain and use authoring.
• Project Structure: where each piece lives in the demo app.