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)

The ssr() function

ssr() is the one server-only hook a page can export. It runs on the server, per render, before the component is rendered to HTML, and returns metadata and seed state. Its mere presence on a static route is what turns that route into a fully server-rendered, cached page.

Signature

00000000001
2
3
4
5
6
7
8
9
export function ssr(): {
  title?: string;          // document <title>
  head?: string;           // extra HTML injected into <head>
  __atoms?: Record<string, any>;  // initial Mimir state for this render
} {
  return { title: "My Page" };
}
 
export default function Page() { /* ... */ }

All fields are optional; returning {} (or nothing) is valid.

`title`

Sets the document title for this page:

00000000001
export function ssr() { return { title: "Pricing, My App" }; }

For dynamic routes, ssr() runs per request for the shell, so you can compute a title from the URL if your setup passes it in (commonly you generate per-entry routes instead, see Programmatic routes).

`head`

Raw HTML appended to <head>. This is where compiled CSS, SEO tags, and the no-FOUC script go. Most apps build head once at startup and pass it to every route's ssr() (or via the route meta), since it is the same for all pages:

00000000001
2
3
4
5
// server.tsx
const head = `<style>${globalCSS}</style>${noFouc}${seo.headTags()}`;
 
// per page (or generated route):
Comp.ssr = function () { return { title, head }; };

For page-specific SEO (a unique description or OG image), call seo.headTags({ ... }) with overrides for that page and return it as head:

00000000001
2
3
4
5
6
7
8
9
export function ssr() {
  return {
    title: "Launch announcement",
    head: seo.headTags({
      description: "We launched X today.",
      og: { image: "https://example.com/og/launch.png", type: "article" },
    }),
  };
}

See SEO.

`__atoms` , seeding state

The most powerful field. __atoms is a map of atom key → value that the server writes into Mimir before rendering. The same values are embedded in __EKKO_DATA__, so the client hydrates with exactly what the server rendered, no flicker, no mismatch.

00000000001
2
3
4
5
6
7
8
9
export function ssr() {
  return {
    title: "Dashboard",
    __atoms: {
      "site-theme": "dark",
      "feature-flags": { beta: true },
    },
  };
}

In a component:

00000000001
const [theme] = useAtom(themeAtom);   // "dark" on the very first client render, from __atoms

Force and merge

By default a seeded value only fills an atom that has no value yet. To override or deep-merge, use the directive form (produced by Mimir's createStore):

{ "__force": true, "__value": v } , overwrite the atom with v.
{ "__merge": true, "__value": v } , deep-merge v into the existing object value.

00000000001
2
3
4
__atoms: {
  "cart": { __force: true, __value: { items: [] } },        // replace
  "prefs": { __merge: true, __value: { density: "compact" } }, // merge into existing prefs
}

The hydration side applies the same rules (mimir.initStore), so server and client agree. Full treatment in Mimir → SSR & hydration.

What `ssr()` is not for

Not per-user data on a cached static route. A static route's render is cached and shared across

users, so do not seed user-specific values into a cached page's __atoms, they would leak the first user's state to everyone. For per-user data, use a dynamic/shell route or fetch after hydration.

Not a place for client-only APIs. ssr() runs on the server; window/document do not exist there.
Not the component. ssr() returns metadata; the default export renders the UI.

Where it runs in the lifecycle

request → match route → ssr() → seed Mimir → renderToString(layout(page)) → htmlShell → cache → respond

Next: when the cache is populated, Strategies.

On this page

Signature title head atoms , seeding state Force and merge What ssr() is not for Where it runs in the lifecycle

The ssr() function

Signature

title

head

__atoms , seeding state

Force and merge

What ssr() is not for

Where it runs in the lifecycle

`title`

`head`

`__atoms` , seeding state

What `ssr()` is not for