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)

Theming

A theme in rune is two things working together: CSS custom properties flipped by a class on <html>, and a Mimir atom that is the single source of truth for which theme is active. Get those two in sync and dark/light "just works", including across navigations, reloads, and the first paint.

The single source of truth: an atom

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

Everything that needs to know the theme reads this atom; everything that changes the theme sets it. Because it is an atom (not component state), the choice survives client navigation, and with a session it survives a reload (see Persistence & sessions).

The CSS side: tokens + the `.dark` class

Define every colour twice, once on :root (the light default) and once on .dark (the override):

00000000001
2
3
4
5
6
7
8
:root {
  --bg:#f7f9fc; --surface:#ffffff; --text:#10151c; --muted:#5b6675;
  --border:#e3e8ef; --accent:#5e81ac;
}
.dark {
  --bg:#0d1117; --surface:#161b22; --text:#e6edf3; --muted:#8a94a3;
  --border:#222b36; --accent:#88c0d0;
}

Components only ever read var(--text), var(--bg), etc. Adding or removing the .dark class on <html> re-themes the entire app, no component-level theme logic.

The bridge: atom → `.dark` class

A tiny client component subscribes to the atom and toggles the class on <html> (and starts the persistence session). Render it once in the root layout so it runs on every page:

00000000001
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
// components/ThemeBridge.tsx
import { useEffect } from "@ekko/react";
import { mimir } from "ekko:rune/mimir";
import { themeAtom } from "../atoms/theme";
 
export default function ThemeBridge() {
  useEffect(() => {
    mimir.session("domain");                  // persist across reloads
    const apply = (v: string) => {
      document.documentElement.classList.toggle("dark", v !== "light");
      try { localStorage.setItem("site-theme", v); } catch {}   // mirror for the no-FOUC script
    };
    apply(mimir.get(themeAtom));
    return mimir.subscribe(themeAtom, apply);  // re-apply on change; cleanup on unmount
  }, []);
  return null;
}

The toggle

00000000001
2
3
4
5
6
7
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 === "dark" ? "🌙" : "☀️"}</button>;
}

No flash on first paint

Two more touches make the first paint correct (no flash of the wrong theme):

Seed the atom in ssr().__atoms so the React tree matches.
Set the .dark class before paint with a tiny inline script reading the mirrored localStorage value.

Both are covered in No-FOUC. The atom keeps React right; the script keeps the very first paint right; the session keeps it across reloads.

"One palette, two declarations" when using a component library

If you also use @ekko/asgard (its components are themed by a JS theme object, not your CSS variables), the brand colours must be declared in two places kept in sync:

the SCSS tokens (:root / .dark) that style your own markup, and
the Asgard theme objects (e.g. lib/theme.ts) that style Asgard components.

The atom is still the single source of truth for which theme is active; both consumers read it. When you change a brand colour, change it in both declarations, or your chrome and the Asgard components will drift. See Asgard integration.

Recap

Piece	Role
`themeAtom`	the source of truth (which theme)
`:root` / `.dark` SCSS tokens	the colours for each theme
`ThemeBridge`	applies the class, starts the session, mirrors to localStorage
`ssr().__atoms` seed	correct React tree on first render
no-FOUC inline script	correct first paint

Next: using the Asgard component + docs UI, Asgard integration.

On this page

The single source of truth: an atom The CSS side: tokens + the .dark class The bridge: atom → .dark class The toggle No flash on first paint "One palette, two declarations" when using a component library Recap