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)

File-based routing

In rune, the filesystem is the route table. Files under pages/ become URLs by their path, no central list to maintain. scanRoutes("pages") reads the directory and produces a sorted list of routes the server registers.

The mapping rules

scanRoutes walks pages/, ignores convention files and tests, and converts each remaining file path to a route pattern:

File	Pattern	Notes
`pages/index.tsx`	`/`	`index` is the segment root
`pages/about.tsx`	`/about`	a plain file
`pages/blog/index.tsx`	`/blog`	nested `index`
`pages/blog/post.tsx`	`/blog/post`	nested file
`pages/blog/[slug].tsx`	`/blog/:slug`	dynamic segment
`pages/shop/[...rest].tsx`	`/shop/*rest`	catch-all
`pages/(marketing)/pricing.tsx`	`/pricing`	`(group)` folders are stripped

The transforms, in the order scanRoutes applies them:

(group)/ and a trailing (group) are removed (grouping without affecting the URL).
[...name] becomes *name (catch-all).
[name] becomes :name (dynamic segment).
index (or a trailing /index) collapses to the segment root.
A leading / is added and trailing slashes trimmed.

Convention files are not routes

These names have special meaning and are skipped by route scanning:

layout.tsx  _layout.tsx   # layouts
loading.tsx               # loading UI
error.tsx   _error.tsx    # error boundary
not-found.tsx             # 404
route.tsx                 # non-page route module

Files containing .test. are skipped too. Everything else is a page.

Route priority and ordering

When several patterns could match a URL, the most specific wins. scanRoutes assigns a priority and sorts:

0 , static routes (/blog/new)
1 , dynamic routes (/blog/:slug)
2 , catch-all routes (/blog/*rest)

So /blog/new is matched by pages/blog/new.tsx even though pages/blog/[slug].tsx also matches the shape, static beats dynamic beats catch-all. Within a priority, routes sort alphabetically for determinism.

Registering the scanned routes

scanRoutes returns objects, not components (it cannot import your modules for you). The idiom is to map each pattern to its imported module:

00000000001
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
import { createApp, scanRoutes, readManifest } from "ekko:rune";
import * as Home from "./pages/index";
import * as About from "./pages/about";
import * as Post from "./pages/blog/[slug]";
 
const app = createApp({ port: 3000, manifest: readManifest() });
 
const modules: any = {
  "/": Home,
  "/about": About,
  "/blog/:slug": Post,
};
 
for (const r of scanRoutes("pages")) {
  const mod = modules[r.pattern];
  if (mod) app.page(r.pattern, mod, { page: r.pageKey });
}
app.start();

Each scanned route carries:

Field	Meaning
`pattern`	The URL pattern (`/blog/:slug`).
`file` / `pageKey`	The page file (the manifest key).
`dynamic`	`true` if it has `:` or `*`.
`catchAll`	`true` for `*`.
`priority`	`0`/`1`/`2` as above.

Why explicit mapping? rune does not auto-import your page files, that would couple the framework to a bundler convention. Listing modules keeps imports explicit and tree-shakeable, and lets you generate routes programmatically (the docs site generates one route per markdown page this way, see Programmatic routes).

Groups: organize without affecting URLs

Wrap files in a (name) folder to group them in your source tree without changing their URLs:

pages/
  (marketing)/
    index.tsx     ->  /
    pricing.tsx   ->  /pricing
  (app)/
    dashboard.tsx ->  /dashboard

Groups are handy for applying different layouts to different sections (see Layouts).

Next: parameters and catch-alls, Dynamic routes.

On this page

The mapping rules Convention files are not routes Route priority and ordering Registering the scanned routes Groups: organize without affecting URLs