router

What it is

@kitr/router is TanStack Router with kitr's defaults. Pages are links on one chain in app/routes.ts, with params typed everywhere. Loaders fill the query cache before a page renders, three guards protect pages, and on phones pages stack like a native app.

Runs in the browser and on the server. A server-only project uses API routes instead.

Install

kitr add router

Adds @kitr/router with TanStack Router and Start, app/routes.ts, app/document.tsx, app/router.tsx and two starter pages. Adds react first if missing. Every UI kit includes it. Every change.

Quick start

Every page is a link on the chain:

// app/routes.ts
import { defineRoutes } from '@kitr/kitr/app'
import router from '@kitr/router/routes'
import { head, RootDocument } from './document'

export const routes = defineRoutes([router], (r) =>
  r
    .root({ head, component: RootDocument })
    .page('/', { lazy: () => import('./pages/home') })
    .page('/about', { lazy: () => import('./pages/about') })
    .page('/projects', { lazy: () => import('./pages/projects') }),
)

export type AppRoutes = typeof routes.$types

kitr make:page projects appends that last line and writes the page. Its default export is the component:

// app/pages/projects.tsx
import { Link } from '@kitr/router'

const projects = [
  { id: 'apollo', name: 'Apollo', team: 'Platform' },
  { id: 'hermes', name: 'Hermes', team: 'Billing' },
]

export default function ProjectsPage() {
  return (
    <main>
      <h1>Projects</h1>
      <ul>
        {projects.map((project) => (
          <li key={project.id}>
            <Link to="/projects/$id" params={{ id: project.id }}>
              {project.name}
            </Link>{' '}
            ({project.team})
          </li>
        ))}
      </ul>
    </main>
  )
}

Open /projects and you see the two projects. The /projects/$id link is a type error until that page exists. lazy loads each page on first visit. Next in the guide: Add your first page.

Built on

kitr adds createKitrRouter, the route table, the guards, the default screens and the native-style page stack.

Problems it solves

• Links that break when a path changes. Map links to URLs.
• Pages that render before their data. Load data before the page renders.
• Guards written per page. Protect pages behind sign-in.
• Search params as untyped strings. Read and write search params.
• Web navigation on a phone. Stack pages like a native app.
• Pages that should not ship everywhere. Limit a route to some platforms.

Further reading

• Guide.
• API reference.
• TanStack Router documentation.
• TanStack Start documentation.
• Query and Auth.
• Platforms.