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)

Tutorial , 1. Create the app

Over the next eight steps you will build Notes, a small but complete rune app: a list of notes, a detail page per note, create/edit, state in Mimir, an API to persist, a themed UI, and a production build. Every chapter of the docs shows up here in context.

By the end you will have used routing (including a dynamic [id] route), a layout, Mimir atoms and a selector, ssr() seeding, an API route, SCSS theming, and the build/deploy flow.

Scaffold first, don't build the project by hand. Create it with ekko init rune notes -t showcase (then cd notes). It writes a correct ekko.json and a working starter. The file listings in this tutorial are explanations so you understand each generated part, not a step-by-step "type these files yourself" guide. Always prefer the scaffold to start; edit the generated files from there.

What we are building

/                 the note list (+ a "new note" form)
/notes/:id        a single note (view / edit)
/api/notes        GET all, POST a new note
/api/notes/:id    GET / PUT one note

Step 1 , the project skeleton

Run ekko init rune notes -t showcase and cd notes , that is the whole of Step 1. It generates exactly the skeleton below. The rest of this page walks through those generated files so you understand what each one does; you do not type them out yourself.

notes/
  ekko.json
  server.tsx
  pages/
    layout.tsx
    index.tsx
    not-found.tsx
  styles/global.scss
  atoms/
  lib/
  static/

`ekko.json`

00000000001
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "name": "notes",
  "version": "1.0.0",
  "type": "rune",
  "entry": "server.tsx",
  "imports": {
    "react": "@ekko/react",
    "react-dom": "@ekko/react-dom",
    "react-dom/server": "@ekko/react-dom/server",
    "react/jsx-runtime": "@ekko/react/jsx-runtime"
  },
  "permissions": { "fs": true, "net": true, "env": true },
  "ship": { "@ekko/react": "^19.0.0", "@ekko/react-dom": "^19.0.0" }
}

`pages/index.tsx` , a placeholder we will grow

00000000001
2
3
4
export function ssr() { return { title: "Notes" }; }
export default function Home() {
  return <main><h1>Notes</h1><p>Coming together over the next steps.</p></main>;
}

`pages/layout.tsx` , the shell

00000000001
2
3
4
5
6
7
8
export default function RootLayout({ children }: { children: any }) {
  return (
    <div className="app">
      <header><a href="/">📝 Notes</a></header>
      <main className="container">{children}</main>
    </div>
  );
}

`pages/not-found.tsx`

00000000001
2
3
export default function NotFound() {
  return <main className="container"><h1>404</h1><p>No such page.</p></main>;
}

`styles/global.scss` , a starting palette

00000000001
2
3
4
5
6
7
8
:root { --bg:#ffffff; --text:#10151c; --muted:#5b6675; --border:#e3e8ef; --accent:#5e81ac; }
.dark { --bg:#0d1117; --text:#e6edf3; --muted:#8a94a3; --border:#222b36; --accent:#88c0d0; }
* { box-sizing: border-box; }
body { margin:0; background:var(--bg); color:var(--text); font-family: Inter, system-ui, sans-serif; }
.container { max-width: 720px; margin: 0 auto; padding: 24px; }
header { padding: 14px 24px; border-bottom: 1px solid var(--border); }
header a { color: var(--text); font-weight: 700; text-decoration: none; }
a { color: var(--accent); }

Step 2 , `server.tsx`

00000000001
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
import "@ekko/react";
import "@ekko/react-dom/server";
import { createApp, scanRoutes, readManifest } from "ekko:rune";
import { compileSass } from "ekko:ssr/css";
import { readText } from "ekko:fs";
 
import RootLayout from "./pages/layout";
import NotFound from "./pages/not-found";
import * as Home from "./pages/index";
 
const head = `<style>${compileSass(readText("styles/global.scss"))}</style>`;
 
const app = createApp({
  port: Number((globalThis as any).Ekko?.env?.get?.("PORT")) || 3000,
  manifest: readManifest(),
  layouts: { "": { layouts: [{ render: RootLayout }] } },
  notFound: NotFound,
  ssr: "eager",
  static: "./static",
  staticPrefix: "/assets",
});
 
const modules: any = { "/": Home };
for (const r of scanRoutes("pages")) {
  const mod = modules[r.pattern];
  if (mod) app.page(r.pattern, mod, { page: r.pageKey, head });
}
 
app.start();
console.log("Notes up on http://localhost:" + (Number((globalThis as any).Ekko?.env?.get?.("PORT")) || 3000));

Step 3 , run it

00000000001
2
ekko build --client
ekko run server.tsx --allow=fs,net,env

Open http://localhost:3000. You should see the header and the placeholder home page, server-rendered (view source to confirm).

If you change a page's rendered output, run ekko build --client again and restart. See The dev loop.

Next: real pages and a dynamic route, 2. Pages and routes.

On this page

What we are building Step 1 , the project skeleton ekko.json pages/index.tsx , a placeholder we will grow pages/layout.tsx , the shell pages/not-found.tsx styles/global.scss , a starting palette Step 2 , server.tsx Step 3 , run it