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)

Pages

A page is the unit of routing: a module under pages/ whose default export is the component for a URL. It may also export ssr() for server-side metadata and seed state. This page is the reference for the page module contract.

The contract

00000000001
2
3
4
5
6
7
8
// pages/about.tsx  →  /about
export function ssr() {
  return { title: "About, My App" };   // optional, server-only
}
 
export default function About() {       // required
  return <main><h1>About</h1></main>;
}

default , the React component rendered for the route. Required, without it the route renders nothing.
ssr() , optional, server-only. Returns { title?, head?, __atoms? }. Its presence makes a static

route a fully server-rendered, cached page. See The ssr() function.

That is the whole contract. A page is "just a component" with one optional server hook.

Registering a page

scanRoutes discovers the file and gives you its pattern and pageKey; you map the pattern to the imported module and call app.page:

00000000001
2
3
4
5
6
import * as About from "./pages/about";
const modules = { "/about": About };
for (const r of scanRoutes("pages")) {
  const mod = modules[r.pattern];
  if (mod) app.page(r.pattern, mod, { page: r.pageKey, head });
}

app.page(path, component, meta) accepts either the module namespace (with default + ssr) or the component directly. The meta.page is the manifest key that tells the server which client chunk to ship.

Props a page receives

For static SSR pages, the component is called with no props (data comes from atoms/imports). For shell routes (dynamic, or static without ssr()), the hydration payload carries props with params, query, and path, and the page reads the location through the router hooks:

00000000001
2
3
4
import { useParams, useSearchParams, useRouter } from "ekko:rune/router";
const { id } = useParams();
const q = useSearchParams();
const { path } = useRouter();

Use the router hooks rather than expecting props, they work on both server and client and keep your component environment-agnostic.

Server vs client execution

A page component runs in two places: on the server during SSR (to produce HTML) and in the browser after hydration (to become interactive). Write it so it produces the same output in both:

Do not read window/document/localStorage during render, seed via ssr().__atoms or read in an

effect (see SSR → hydration).

ssr() runs only on the server, it is the right place for server-only metadata, never for client UI.

Pages vs components

Everything under pages/ (except convention files) is a route. Everything under components/ is a plain component you import, not a route. A page typically composes components:

00000000001
2
3
4
// pages/index.tsx
import Hero from "../components/Hero";
import Features from "../components/Features";
export default function Home() { return <><Hero /><Features /></>; }

Convention files are not pages

layout.tsx, error.tsx, not-found.tsx, loading.tsx, route.tsx (and _-prefixed variants) have special roles and are not registered as routes. See Conventions.

Next: the chrome around pages, Layouts.

On this page

The contract Registering a page Props a page receives Server vs client execution Pages vs components Convention files are not pages