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)

Tutorial , 2. Pages and routes

Now we give Notes its routes: a list at / and a detail page at /notes/:id. The detail page is a dynamic route, our first [id] file.

Some seed data

Until we add an API (step 6), keep notes in a plain module so pages have something to show:

00000000001
2
3
4
5
6
7
8
9
10
11
// lib/notes.ts
export type Note = { id: string; title: string; body: string };
 
export const seedNotes: Note[] = [
  { id: "welcome", title: "Welcome", body: "This is your first note." },
  { id: "ideas",   title: "Ideas",   body: "- ship rune\n- write docs" },
];
 
export function findNote(id: string, notes: Note[]) {
  return notes.find(n => n.id === id) || null;
}

The list page

00000000001
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
// pages/index.tsx
import { Link } from "ekko:rune/router";
import { seedNotes } from "../lib/notes";
 
export function ssr() { return { title: "Notes" }; }
 
export default function Home() {
  return (
    <section>
      <h1>Notes</h1>
      <ul className="note-list">
        {seedNotes.map(n => (
          <li key={n.id}>
            <Link href={`/notes/${n.id}`}>{n.title}</Link>
          </li>
        ))}
      </ul>
    </section>
  );
}

Note the <Link>, in-app navigation, so clicking a note will not reload the page.

The dynamic detail route

Create pages/notes/[id].tsx. The [id] in the filename becomes the route /notes/:id, and useParams() gives us the id:

00000000001
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
// pages/notes/[id].tsx
import { useParams, Link } from "ekko:rune/router";
import { seedNotes, findNote } from "../../lib/notes";
 
export function ssr() { return { title: "Note" }; }
 
export default function NotePage() {
  const { id } = useParams();
  const note = findNote(id, seedNotes);
  if (!note) return <p>Note not found. <Link href="/">Back</Link></p>;
  return (
    <article>
      <Link href="/">← All notes</Link>
      <h1>{note.title}</h1>
      <pre className="note-body">{note.body}</pre>
    </article>
  );
}

Register both routes

server.tsx maps patterns to modules. Add the import and the mapping:

00000000001
2
3
4
5
6
7
import * as Home from "./pages/index";
import * as NotePage from "./pages/notes/[id]";
 
const modules: any = {
  "/": Home,
  "/notes/:id": NotePage,    // [id] -> :id
};

The scanRoutes loop already registers anything in modules, so no other change is needed. (Recall: scanRoutes returns the pattern /notes/:id for the file pages/notes/[id].tsx.)

Dynamic routes render on the client

/notes/:id is a dynamic route, so the server returns a shell and the page renders on the client using params. The ssr() still sets the title. This is exactly the behaviour described in Dynamic routes, the body depends on the URL, so it is not pre-cached.

Run and click around

00000000001
ekko build --client && ekko run server.tsx --allow=fs,net,env

/ lists the two seed notes.
Clicking one navigates to /notes/welcome without a reload (watch, no flash; the header stays put).
A bad id (/notes/nope) shows the "not found" branch.

A little CSS

00000000001
2
3
.note-list { list-style: none; padding: 0; }
.note-list li { padding: 10px 0; border-bottom: 1px solid var(--border); }
.note-body { white-space: pre-wrap; background: var(--border); padding: 12px; border-radius: 8px; }

Restart the server to pick up SCSS changes.

Next: a richer shell and shared chrome, 3. Layouts.

On this page

Some seed data The list page The dynamic detail route Register both routes Dynamic routes render on the client Run and click around A little CSS