alepha@docs:~/docs/guides/frontend$
cat 2-routing.md | pretty
6 min read
Last commit:

#Routing

Alepha uses the $page primitive to define React routes. It is a superset of $route designed specifically for React pages with support for data loading, code splitting, SSR, SSG, nested routing, and type-safe parameters.

#Setup

typescript 
1import { $page } from "alepha/react/router";

Routes are defined as class properties. The class is registered with the Alepha instance in your entry files.

#Defining Pages

A complete example from a real Alepha application:

typescript 
 1import { t } from "alepha"; 2import { $page } from "alepha/react/router"; 3import { $client } from "alepha/server/links"; 4import type { CountApi } from "./CountApi.ts"; 5  6export class AppRouter { 7  countApi = $client<CountApi>(); 8  9  home = $page({10    head: { title: "Home" },11    schema: {12      query: t.object({13        name: t.text({ default: "Alepha" }),14      }),15    },16    loader: async ({ query }) => {17      return {18        greeting: `Hello, ${query.name} SSR!`,19        count: await this.countApi.inc().then((result) => result.count),20      };21    },22    lazy: () => import("./Home.tsx"),23  });24 25  about = $page({26    head: { title: "About" },27    path: "/about",28    lazy: () => import("./About.tsx"),29  });30}

#Page Options

#path

URL pattern with parameter support. If omitted, defaults to the root (/).

typescript 
1path: "/users/:id"2path: "/blog/:slug"

#schema

Type-safe URL parameters and query strings using TypeBox schemas.

typescript 
1schema: {2  params: t.object({ id: t.integer() }),3  query: t.object({ tab: t.optional(t.text()) }),4}

Parameters and query values are validated and typed in the loader and component props.

#loader

Server-side data fetching function. Receives typed params, query, and parent props. The returned data is passed to the component as props. In SSR, data is serialized on the server and hydrated on the client.

typescript 
1loader: async ({ params, query }) => {2  const user = await this.userApi.getUser(params.id);3  return { user };4}

#component and lazy

Provide the React component to render. Use lazy for code splitting (recommended):

typescript 
1// Code splitting (recommended)2lazy: () => import("./UserProfile.tsx")3 4// Direct component5component: ({ user }) => <div>{user.name}</div>

Lazy-loaded modules must use a default export.

#head

Set document head tags (title, meta, etc.). Can be static or dynamic:

typescript 
1// Static2head: { title: "About Us" }3 4// Dynamic, based on loader data5head: (props) => ({6  title: props.user.name,7  description: `Profile of ${props.user.name}`,8})

#static

Pre-render the page at build time (SSG). On the server, acts as a cached page.

typescript 
 1// Simple static page 2static: true 3  4// With predefined entries 5static: { 6  entries: [ 7    { params: { slug: "hello-world" } }, 8    { params: { slug: "getting-started" } }, 9  ],10}

#client

Force client-side only rendering (no SSR). Uses the <ClientOnly /> component internally.

typescript 
1client: true

#cache

Server-side caching configuration. Automatically set when static: true.

typescript 
1cache: {2  store: {3    provider: "memory",4    ttl: [1, "hour"],5  },6}

#can

Permission-based access control. Return false to block access (results in 403).

typescript 
1can: () => userHasPermission("admin")

#Nested Routing

Define parent-child relationships between pages using parent on the child or children on the parent. Parent pages render child content using the <NestedView /> component.

#Which option to use

The choice is not stylistic — it depends on who owns the child page:

  • You own the child (you wrote the $page and can edit it) → set parent on the child. The child declares its own place in the tree.
  • You don't own the child (it comes from another package or an injected router you can't modify) → add it to children on your parent. The parent adopts pages it doesn't control.

The second case is the reason children exists. When you $inject a router from another package, its $page definitions are frozen — you can't reach in and set parent on them. children is how you mount those external pages under one of your own layouts:

typescript 
 1class AppRouter { 2  protected productRouter = $inject(ProductRouter); 3  4  layout = $page({ 5    path: "/app", 6    component: () => <Shell><NestedView /></Shell>, 7    children: () => [ 8      this.productRouter.catalogPage, 9      this.productRouter.checkoutPage,10    ],11  });12}

When you do own the child, prefer parent — it keeps parents free of forward references to their own descendants and reads top-down:

typescript 
 1import { $page } from "alepha/react/router"; 2import { NestedView } from "alepha/react/router"; 3  4class AppRouter { 5  layout = $page({ 6    path: "/app", 7    component: () => ( 8      <div> 9        <nav>Sidebar</nav>10        <main>11          <NestedView />12        </main>13      </div>14    ),15  });16 17  dashboard = $page({18    path: "/dashboard",19    parent: this.layout,20    lazy: () => import("./Dashboard.tsx"),21  });22 23  settings = $page({24    path: "/settings",25    parent: this.layout,26    lazy: () => import("./Settings.tsx"),27  });28}

⚠️ Declare each edge from one side only. If page B already has parent: pageA, do not also list B in pageA.children. The link is already established; stating it on both sides creates a TypeScript circular dependency between the two class fields (each references the other before it is initialised).

<NestedView /> renders the matched child page. It supports an optional errorBoundary prop.

#Error Handling

Use errorHandler to catch loader or rendering errors. Return a ReactNode for a custom error page, a Redirection to redirect, or undefined to let the error propagate to parent pages.

typescript 
 1import { Redirection } from "alepha/react/router"; 2  3errorHandler: (error) => { 4  if (HttpError.is(error, 404)) { 5    return <NotFound />; 6  } 7  if (HttpError.is(error, 401)) { 8    return new Redirection("/login"); 9  }10}

#Lifecycle Callbacks

  • onEnter -- called when the user enters the page (browser only)
  • onLeave -- called when the user leaves the page (browser only)
typescript 
1onEnter: () => {2  analytics.trackPageView("/dashboard");3  window.scrollTo(0, 0);4}
  • onServerResponse -- called before the server sends the response (server only)

#Page Animations

CSS-based enter/exit animations (experimental).

typescript 
 1// Simple animation name 2animation: "fadeIn" 3  4// Detailed enter/exit 5animation: { 6  enter: { name: "fadeIn", duration: 300 }, 7  exit: { name: "fadeOut", duration: 200, timing: "ease-in-out" }, 8} 9 10// Dynamic based on router state11animation: (state) => ({12  enter: "slideIn",13  exit: "slideOut",14})

Define the keyframes in your CSS:

css 
1@keyframes fadeIn {2  from { opacity: 0; }3  to { opacity: 1; }4}

#Router Hooks

#useRouter

Access the router for navigation. Accepts a type parameter for type-safe page name references.

typescript 
 1import { useRouter } from "alepha/react/router"; 2  3function Nav() { 4  const router = useRouter<AppRouter>(); 5  6  return ( 7    <div> 8      <p>Current path: {router.pathname}</p> 9      <button onClick={() => router.push("/about")}>About</button>10      <button onClick={() => router.push("home")}>Home (by name)</button>11      <button onClick={() => router.back()}>Back</button>12      <button onClick={() => router.forward()}>Forward</button>13      <button onClick={() => router.reload()}>Reload</button>14    </div>15  );16}

Key methods and properties:

Method/Property Description
push(path, opts) Navigate to a path or page name. Options: replace, params, query, force.
back() Go back in history.
forward() Go forward in history.
reload() Reload the current page.
isActive(href) Check if the given path is the current route.
pathname Current pathname string.
query Current query parameters as Record<string, string>.
path(name, cfg) Resolve a page name to its URL path.
anchor(path) Returns { href, onClick } props for anchor elements.
setQueryParams(record) Update URL query parameters without navigation.

#useActive

Determine if a route is active and get anchor props for navigation links.

typescript 
 1import { useActive } from "alepha/react/router"; 2  3function NavLink({ href, label }: { href: string; label: string }) { 4  const { isActive, isPending, anchorProps } = useActive(href); 5  6  return ( 7    <a {...anchorProps} className={isActive ? "active" : ""}> 8      {isPending ? "Loading..." : label} 9    </a>10  );11}

Accepts a string or an options object:

typescript 
1const { isActive } = useActive({ href: "/docs", startWith: true });2// isActive is true for /docs, /docs/intro, /docs/api, etc.

#useQueryParams

Manage typed query parameters with a schema.

typescript 
 1import { useQueryParams } from "alepha/react/router"; 2import { t } from "alepha"; 3  4function SearchPage() { 5  const [params, setParams] = useQueryParams( 6    t.object({ 7      search: t.optional(t.text()), 8      page: t.optional(t.integer()), 9    }),10  );11 12  return (13    <input14      value={params.search ?? ""}15      onChange={(e) => setParams({ ...params, search: e.target.value })}16    />17  );18}

Options:

Option Type Default Description
key string "q" Param name for base64 format. Ignored by querystring.
format "base64" | "querystring" "base64" base64 packs the whole object into one opaque param (?q=…); querystring spreads each field as its own readable param (?search=…&page=…).
push boolean false true adds a history entry (pushState) so back returns to the previous value; false replaces the current entry (replaceState).

With format: "querystring", each schema field maps to its own URL param, and values are coerced back to their declared types on read (e.g. an t.integer() field reads ?page=2 as the number 2).

#Links and Anchor Interception

Plain <a href="/..."> anchors are intercepted automatically and routed through the SPA router — no <Link> wrapper required. This works inside React JSX as well as in raw HTML injected into the page (e.g. Markdown content rendered from a CMS).

html 
1<a href="/about">About</a>

The interceptor bails out (and lets the browser handle the click natively) when any of the following apply:

  • the click uses a modifier key (meta, ctrl, shift, alt)
  • the mouse button isn't the primary one (middle/right click)
  • the anchor has target other than _self (e.g. target="_blank")
  • the anchor has a download attribute
  • the anchor has a data-no-router attribute (explicit opt-out)
  • the href uses a non-http(s) scheme (mailto:, tel:, data:, …)
  • the href points to a different origin
  • the href is hash-only (#section)
  • another listener already called event.preventDefault()

To force a hard navigation on a same-origin link, opt out per-anchor:

html 
1<a href="/legacy" data-no-router>Legacy page</a>

To disable the global interceptor, set interceptAnchorClicks: false on the alepha.react.browser.options atom.

# component

<Link> is still available as a thin wrapper around <a> that wires the router via onClick directly:

typescript 
1import { Link } from "alepha/react/router";2 3<Link href="/about">About</Link>

With the global interceptor enabled, <Link> is mostly a stylistic preference. Reach for it when you want explicit per-link control or intend to extend it with prefetching/active-state logic later.

#Router Events

Route transitions emit events on the Alepha event system:

  • react:transition:begin -- navigation started (includes previous and new state)
  • react:transition:success -- navigation completed
  • react:transition:error -- navigation failed
  • react:transition:end -- always emitted after transition completes