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 manifest

ekko build --client writes .ekko/build/manifest.json. It is the contract between the build and the running server: the build says "here are the client chunks and how they relate", and the server uses it to emit exactly the right <script type="module"> and <link rel="modulepreload"> tags per page. You rarely read it by hand, but understanding it explains how SSR pages know which JavaScript to load.

Shape

00000000001
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
  // the client bootstrap that runs first and hydrates the page
  "hydrate": "_hydrate-ZTXJDWFL.js",
 
  // one entry per page module (keyed by the page file)
  "pages": {
    "index.tsx":  { "file": "pages/index-LNH6OYEF.js",  "imports": ["chunks/chunk-5UQ65DYX.js"], "css": [] },
    "docs.tsx":   { "file": "pages/docs-SOX5ENF4.js",   "imports": ["chunks/chunk-QB4JIDOU.js"], "css": [] },
    "layout.tsx": { "file": "pages/layout-FC6L7ZBH.js", "imports": [ ... ] }
  },
 
  // shared chunks pulled in by multiple pages
  "chunks": [ "chunks/chunk-5UQ65DYX.js", "chunks/chunk-QB4JIDOU.js" ],
 
  // global stylesheets (linked on every page)
  "styles": [],
 
  // route metadata the CLI generated while scanning pages/
  "routes": [ { "page": "index.tsx", "pattern": "/", "priority": 0 } ]
}

Filenames are content-hashed (index-LNH6OYEF.js), so they can be served with a long immutable cache: a change produces a new name, never a stale cache.

How the server uses it

readManifest() loads the JSON; you pass it to createApp({ manifest }). For each page, the server calls resolvePageAssets(manifest, pageKey) which collects, in order:

the hydrate entry (added to modules + modulepreload) and its imports (preloaded),
global styles,
the page's file (the page chunk) and its imports (preloaded) and css,
the layout chunk and its imports (preloaded),

then deduplicates the preload list. The result feeds htmlShell(...), which renders:

00000000001
2
3
4
<link rel="modulepreload" href="/_ekko/_hydrate-ZTXJDWFL.js">
<link rel="modulepreload" href="/_ekko/pages/index-LNH6OYEF.js">
<link rel="modulepreload" href="/_ekko/chunks/chunk-5UQ65DYX.js">
<script type="module" src="/_ekko/_hydrate-ZTXJDWFL.js"></script>

modulepreload warms the chunks the page will import the instant hydration runs, so there is no waterfall.

The `pageKey`

When you register a route you pass meta.page (the page key, e.g. "index.tsx"). That is the key into manifest.pages. scanRoutes("pages") returns this as r.pageKey, which is why the typical loop is:

00000000001
2
3
4
for (const r of scanRoutes("pages")) {
  const mod = modules[r.pattern];
  if (mod) app.page(r.pattern, mod, { page: r.pageKey });   // r.pageKey -> manifest.pages[...]
}

If the key is missing from the manifest (you forgot to rebuild the client), the page still server-renders, but it ships no hydration script, so it will not become interactive. The fix is always: ekko build --client.

Where it is served from

The build output under .ekko/build/client/ is mounted at /_ekko with maxAge: 31536000, immutable. So pages/index-LNH6OYEF.js is fetched as /_ekko/pages/index-LNH6OYEF.js. You never reference these URLs yourself; the manifest + server do.

Shipping it

.ekko/build/ is part of your app bundle. In production you build the client on your dev machine and ship the .ekko/build folder, the prod box does not (and need not) rebuild client code. See The build and Production deploy.

Next: project configuration, Configuration.

On this page

Shape How the server uses it The pageKey Where it is served from Shipping it