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)

Mimir patterns

Concrete, copy-pasteable patterns for the state you actually build. Each is small on purpose, Mimir's value is that these stay small.

Theme toggle (persisted, no flicker)

00000000001
2
3
// atoms/theme.ts
import { atom } from "ekko:rune/mimir";
export const themeAtom = atom({ key: "site-theme", default: "dark" });

00000000001
2
3
4
5
6
7
8
// a toggle anywhere
import { useAtom } from "ekko:rune/mimir";
import { themeAtom } from "../atoms/theme";
 
export function ThemeToggle() {
  const [theme, setTheme] = useAtom(themeAtom);
  return <button onClick={() => setTheme(t => t === "dark" ? "light" : "dark")}>{theme}</button>;
}

Seed it from ssr() and apply the .dark class with the no-FOUC script so the first paint is correct too (see No-FOUC and Theming). With a domain session it survives reloads.

A bridge that mirrors an atom to the DOM

Theming needs the .dark class on <html>; subscribe to the atom and toggle the class:

00000000001
2
3
4
5
6
7
8
9
10
11
12
import { useEffect } from "@ekko/react";
import { mimir } from "ekko:rune/mimir";
import { themeAtom } from "../atoms/theme";
 
export default function ThemeBridge() {
  useEffect(() => {
    const apply = (v: string) => document.documentElement.classList.toggle("dark", v !== "light");
    apply(mimir.get(themeAtom));
    return mimir.subscribe(themeAtom, apply);
  }, []);
  return null;
}

Keep an in-progress form in an atom so leaving and returning (or an accidental nav) does not lose it:

00000000001
2
3
4
5
6
7
8
9
10
11
const draftAtom = atom({ key: "contact:draft", default: { name: "", message: "" } });
 
function ContactForm() {
  const [draft, setDraft] = useAtom(draftAtom);
  return (
    <form>
      <input value={draft.name} onChange={e => setDraft(d => ({ ...d, name: e.target.value }))} />
      <textarea value={draft.message} onChange={e => setDraft(d => ({ ...d, message: e.target.value }))} />
    </form>
  );
}

Mark it persist: false if a reload should clear it; leave the default persist: true (with a session) to keep it across reloads.

A persisted list (todo / cart): add, toggle, remove

The most common real case is an array of objects you add to, toggle, and remove, persisted across a reload. Keep the list in one atom and update it immutably with the functional set(prev => …) form:

00000000001
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
import { atom, useAtom } from "ekko:rune/mimir";
 
type Todo = { id: string; text: string; done: boolean };
export const todosAtom = atom<Todo[]>({ key: "todos:list", default: [], persist: true });
 
function Todos() {
  const [todos, setTodos] = useAtom(todosAtom);
 
  const add    = (text: string) => setTodos(list => [...list, { id: crypto.randomUUID(), text, done: false }]);
  const toggle = (id: string)   => setTodos(list => list.map(t => t.id === id ? { ...t, done: !t.done } : t));
  const remove = (id: string)   => setTodos(list => list.filter(t => t.id !== id));
 
  return (
    <ul>
      {todos.map(t => (
        <li key={t.id}>
          <input type="checkbox" checked={t.done} onChange={() => toggle(t.id)} />
          <span>{t.text}</span>
          <button onClick={() => remove(t.id)}>delete</button>
        </li>
      ))}
    </ul>
  );
}

Because todosAtom is persist: true and the session is active, the list survives a full reload. Always update with the functional form (set(prev => …)) so concurrent updates don't clobber each other. (Verify persistence in a real browser, not via curl, the server renders the default [].)

Store fetched data in an atom plus a loading flag; many components read the same result:

00000000001
2
3
4
5
6
7
8
9
10
11
12
const usersAtom   = atom({ key: "users:list", default: [] as User[] });
const loadingAtom = atom({ key: "users:loading", default: false });
 
async function loadUsers() {
  mimir.set(loadingAtom, true);
  try {
    const res = await fetch("/api/users");
    mimir.set(usersAtom, await res.json());
  } finally {
    mimir.set(loadingAtom, false);
  }
}

00000000001
2
3
4
5
6
function UserList() {
  const users = useAtomValue(usersAtom);
  const loading = useAtomValue(loadingAtom);
  if (loading) return <Spinner />;
  return <ul>{users.map(u => <li key={u.id}>{u.name}</li>)}</ul>;
}

Trigger loadUsers() from an effect or an event; every component reading usersAtom updates together. See Data fetching.

Derived totals with a selector

00000000001
2
3
4
5
6
7
const cartAtom = atom({ key: "cart:items", default: [] as Item[] });
 
export const cartCount = selector({ key: "cart:count", get: ({ get }) => get(cartAtom).length });
export const cartTotal = selector({
  key: "cart:total",
  get: ({ get }) => get(cartAtom).reduce((s, i) => s + i.price * i.qty, 0),
});

The header badge reads cartCount, the checkout reads cartTotal, both update precisely when the cart changes, never on unrelated state. See Selectors.

A filtered, sorted view

00000000001
2
3
4
5
6
7
8
9
10
const queryAtom = atom({ key: "search:q", default: "" });
const itemsAtom = atom({ key: "items", default: [] as Item[] });
 
export const visibleItems = selector({
  key: "items:visible",
  get: ({ get }) => {
    const q = get(queryAtom).toLowerCase();
    return get(itemsAtom).filter(i => i.name.toLowerCase().includes(q)).sort(byName);
  },
});

The list view reads visibleItems; typing in the search box sets queryAtom; the selector recomputes. No manual recompute calls, no stale lists.

Cross-component coordination (no prop drilling)

A sidebar's open/closed state, read by the toggle button, the overlay, and the layout, lives in one atom:

00000000001
export const sidebarOpen = atom({ key: "ui:sidebar-open", default: false });

The button calls useSetAtom(sidebarOpen); the overlay and layout useAtomValue(sidebarOpen). They are nowhere near each other in the tree, and there is no context provider, they just import the same atom.

Next: the mistakes to avoid, Pitfalls.

On this page

Theme toggle (persisted, no flicker)A bridge that mirrors an atom to the DOM Form draft that survives navigation A persisted list (todo / cart): add, toggle, remove Async data (load once, share everywhere)Derived totals with a selector A filtered, sorted view Cross-component coordination (no prop drilling)