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)

Recipe , data fetching

Where you fetch data depends on whether it should be in the server-rendered HTML (for first paint and SEO) or loaded after hydration (for per-user or frequently-changing data). rune supports both.

Option A , data available at render (best first paint)

If the data is available on the server (a module import, a database the server can read, a value computed at startup), render with it directly, no fetch needed. The list is in the HTML and indexable.

00000000001
2
3
4
5
6
7
8
9
// data lives in a module the server imports
import { allPosts } from "../lib/posts";
 
export function ssr() { return { title: "Blog" }; }
 
export default function Blog() {
  const posts = allPosts();        // runs on the server (and client, if the data is bundled)
  return <ul>{posts.map(p => <li key={p.id}>{p.title}</li>)}</ul>;
}

For a known set, register one cached static route per item so each is fully rendered (see Programmatic routes). For an embedded dataset (like these docs), import a generated *.data.ts and render from memory, navigation is instant, no network.

Option B , seed via `ssr().__atoms`

Compute data on the server and seed it into an atom so the first client render already has it (and components reading the atom update together):

00000000001
2
3
4
5
import { latestPosts } from "../lib/posts";
 
export function ssr() {
  return { title: "Home", __atoms: { "posts:latest": latestPosts(5) } };
}

00000000001
const posts = useAtomValue(postsLatestAtom);   // populated from __atoms on first render

On a cached static page, only seed non-personal data (the HTML is shared). For per-user data, use option C. See Mimir → SSR & hydration.

Option C , fetch after hydration (per-user / live data)

For data that is per-user or changes often, fetch from a same-process API route after mount and store it in an atom:

00000000001
2
3
4
5
6
7
8
9
10
11
12
13
const usersAtom   = atom({ key: "users:list", default: [] as User[] });
const loadingAtom = atom({ key: "users:loading", default: false });
 
export default function Users() {
  const [users, setUsers] = useAtom(usersAtom);
  const [loading, setLoading] = useAtom(loadingAtom);
  useEffect(() => {
    setLoading(true);
    fetch("/api/users").then(r => r.json()).then(u => { setUsers(u); setLoading(false); });
  }, []);
  if (loading && users.length === 0) return <Spinner />;
  return <ul>{users.map(u => <li key={u.id}>{u.name}</li>)}</ul>;
}

Storing in an atom (not local state) means the data survives navigation, navigate away and back and it is still there, no refetch.

The API side

00000000001
2
3
4
5
6
app.api("GET", "/api/users", () => listUsers());
app.api("GET", "/api/users/:id", async (req, res) => {
  const u = getUser(req.params.id);
  if (!u) { res.status(404); return { error: "not found" }; }
  return u;
});

Same process, so the API reads the same data the pages render from, no second service, no CORS.

Caching and revalidation

Page-level: static SSR pages are cached; bust them when underlying data changes with

app.invalidate("/posts") or a tag. See Caching & invalidation.

Client-level: keep fetched data in atoms; refetch on an interval or on a user action, and update the

atom. The atom is your client cache.

Choosing

Data	Approach
Static/known, want SEO + instant nav	render from a module / embedded data (A)
Server-known, page-specific	seed via `ssr().__atoms` (B)
Per-user or live	fetch after hydration into an atom (C)
Mutates at runtime, cached pages	API mutation + `app.invalidate`

Most apps mix these: marketing/docs use A, a dashboard's shell uses A/B and its live widgets use C.

On this page

Option A , data available at render (best first paint)Option B , seed via ssr().atoms Option C , fetch after hydration (per-user / live data)The API side Caching and revalidation Choosing