Docs

Introduction

What is rune

Philosophy

Why rune

Architecture

Getting Started

Installation

Quick start

Project structure

The dev loop

Tutorial: build an app

1. Create the app

2. Pages & routes

3. Layouts

4. State with Mimir

5. SSR & data

6. API routes

7. Styling

8. Build & deploy

Core Concepts

The application object

Rendering pipeline

Hydration

The build manifest

Configuration (ekko.json)

Permissions

Conventions

Routing

File-based routing

Dynamic routes

The router (useRouter)

Navigation & Link

Guards & redirects

Programmatic routes

Server-Side Rendering

Overview

The ssr() function

Strategies (eager/lazy)

SSR → hydration

Caching & invalidation

SEO

Mimir, state management

Overview

Atoms

Reading & writing

Selectors (derived state)

Subscriptions & the store

SSR & hydration

Persistence & sessions

Patterns & recipes

Pitfalls

Pages & Layouts

Pages

Layouts

Error & not-found

API Routes

Defining routes

Request & response

Middleware

helmet

cors

rateLimit

bodyLimit

validateContentType

csrf

requestId

timeout

errorHandler

httpsRedirect

secureCookies

ipFilter

safePath

Validation & options

Styling & Theming

SCSS

Theming (light/dark)

Asgard integration

No flash (no-FOUC)

Building & Deploying

The build

Static assets

Production deploy

API Reference

ekko:rune

ekko:rune/router

ekko:rune/mimir

ekko:rune/seo

ekko:ssr / css

ekko.json schema

CLI commands

Guides

Rune app from scratch

Recipes

Dark mode

Forms

Data fetching

Authentication

Pagination

FAQ (use cases)

The router

After hydration, navigation is the client router's job. ekko:rune/router exposes hooks to read the current location and functions to change it, all without a server round-trip.

00000000001
import { useRouter, useParams, useSearchParams, navigate, Link } from "ekko:rune/router";

`useRouter()`

Returns a live object describing the current location and the navigation controls:

00000000001
2
3
4
5
6
7
8
const router = useRouter();
 
router.path      // string  , current pathname, e.g. "/docs/getting-started"
router.params    // object  , route params from the matched pattern, e.g. { slug: "x" }
router.query     // object  , parsed query string, e.g. { tab: "overview" }
router.navigate  // (href, opts?) => void  , client navigation (no reload)
router.back      // () => void  , history back
router.forward   // () => void  , history forward

The hook subscribes to route changes, so a component using useRouter() re-renders when the URL changes (including on back/forward).

00000000001
2
3
4
export default function Breadcrumb() {
  const { path } = useRouter();
  return <small>You are at {path}</small>;
}

`useParams()` and `useSearchParams()`

Focused hooks if you only need part of the location:

00000000001
2
const { id } = useParams();           // route params only
const search = useSearchParams();     // query object only (parsed from location.search)

useParams() reads the params extracted when the current route was matched against __routes. useSearchParams() parses location.search into an object.

`navigate(href, opts?)`

Imperatively navigate on the client:

00000000001
2
3
4
5
6
import { navigate } from "ekko:rune/router";
 
function onSave() {
  // ... persist ...
  navigate("/dashboard");
}

navigate matches href against the client route table, imports the target page's chunk (cached after the first time), renders it inside the layout, and updates history. No full page load. On the server (during SSR) navigate is a no-op, the server does not navigate.

How matching works on the client

The hydration payload includes __routes: an array of { pattern, pageFile, guard } sorted static → dynamic → catch-all (the same priority order as the server). On a navigation the router:

Splits href into pathname + query.
Walks __routes in priority order, testing each pattern (:param matches one segment, *rest matches

the remainder).

On the first match, records the extracted params, dynamically imports pageFile, and renders.

Because the route table is baked into the page, matching is instant and offline-capable, no request needed to decide where a link goes.

Any component using useRouter()/useParams()/useSearchParams() re-renders on navigation. For side-effects (analytics, scroll restoration), use an effect keyed on router.path:

00000000001
2
const { path } = useRouter();
useEffect(() => { track("pageview", path); window.scrollTo(0, 0); }, [path]);

Server vs client

	Server (SSR)	Client (after hydrate)
`useRouter().path`	the request path	the live pathname
`navigate(...)`	no-op	client navigation
`params`/`query`	from the request	from the matched route / `location.search`

This means you can call useRouter() in a component that renders on both, it returns sensible values in each environment, and your component does not need to branch on "am I on the server".

Next: links and the navigation rules, Navigation.

On this page

useRouter()useParams() and useSearchParams()navigate(href, opts?)How matching works on the client Reacting to navigation Server vs client