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)

API routes

A rune app is also your backend. app.api(method, path, [opts], handler) registers an HTTP endpoint in the same process as your pages, no separate server, no CORS, no type boundary. The pages and the API read the same in-memory data.

00000000001
2
3
4
5
6
app.api("GET",  "/api/health",      ()    => ({ ok: true }));
app.api("GET",  "/api/notes",       ()    => allNotes());
app.api("GET",  "/api/notes/:id",   (req) => findNote(req.params.id));
app.api("POST", "/api/notes",       async (req) => createNote(await req.json()));
app.api("PUT",  "/api/notes/:id",   async (req) => updateNote(req.params.id, await req.json()));
app.api("DELETE","/api/notes/:id",  (req) => deleteNote(req.params.id));

Signature

00000000001
2
app.api(method, path, handler);
app.api(method, path, opts, handler);   // with options

method , "GET" | "POST" | "PUT" | "DELETE" | "PATCH" (case-insensitive).
path , the URL pattern, supports :param segments (/api/notes/:id).
opts , optional per-route options (passed to the underlying server, e.g. body limits).
handler , (req, res) => ....

Returns app, so you can chain.

Returning vs writing

The handler can return a value or write to res, returning is the concise path:

00000000001
2
3
4
5
6
7
8
9
10
11
12
// return an object → sent as JSON automatically
app.api("GET", "/api/me", (req) => ({ user: req.user }));
 
// return a string → sent as text
app.api("GET", "/api/ping", () => "pong");
 
// or write to res explicitly for full control
app.api("GET", "/api/raw", (_req, res) => {
  res.status(200);
  res.header("Content-Type", "text/csv");
  res.send("a,b\n1,2");
});

If the handler returns a value and has not already written to res, rune sends it: objects/arrays as JSON, anything else as text. If you write to res yourself, return nothing.

Params

:param segments are parsed into req.params:

00000000001
2
3
4
app.api("GET", "/api/users/:id/posts/:postId", async (req) => {
  const { id, postId } = req.params;
  return getPost(id, postId);
});

Errors are caught

If a handler throws, rune catches it, logs it server-side, and responds 500 { error } rather than crashing the process. You can still set explicit statuses for expected errors:

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

The "same process" advantage

Because the API and the pages run together, you get patterns that are awkward in a split stack:

00000000001
2
3
4
5
app.api("POST", "/api/notes", async (req) => {
  const note = createNote(await req.json());   // mutate the shared store
  app.invalidate("/");                 // re-render the cached list page
  return { id: note.id };
});

The page render, the API, and the cache live in one place: the API mutates the data the pages render, and busts the page cache directly. See Caching & invalidation.

Organising routes

00000000001
2
3
4
5
// lib/api/notes.ts
export function registerNoteRoutes(app) {
  app.api("GET", "/api/notes", () => allNotes());
  app.api("POST", "/api/notes", async (req) => createNote(await req.json()));
}

00000000001
2
3
// server.tsx
import { registerNoteRoutes } from "./lib/api/notes";
registerNoteRoutes(app);

Next: the request and response objects in detail, Request & response.

On this page

Signature Returning vs writing Params Errors are caught The "same process" advantage Organising routes