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 , authentication

A session-cookie auth flow in rune: middleware attaches the user to every request, the server seeds it into the page so components know who is logged in without a round-trip, and guarded routes redirect.

Permission: hashing passwords uses ekko:crypto (pbkdf2), which needs the crypto permission. Run an auth app with ekko run server.tsx --allow=fs,net,env,crypto (the ekko init rune scaffold already adds "crypto": true to its ekko.json). Without it the first hash throws PermissionError: crypto access denied.

1. Middleware attaches `req.user`

00000000001
2
3
4
5
6
// server.tsx
app.use((req, _res, next) => {
  const token = parseCookie(req.headers["cookie"] || "")["session"];
  req.user = token ? verifySession(token) : null;   // your verification; null when anonymous
  next();
});

Now every API handler and the SSR layer can read req.user. rune carries it into the page data as __user.

00000000001
2
3
4
5
6
7
8
9
10
11
12
13
14
app.api("POST", "/api/login", async (req, res) => {
  const { email, password } = await req.json() ?? {};
  const user = authenticate(email, password);
  if (!user) { res.status(401); return { error: "invalid credentials" }; }
  const token = createSession(user.id);
  res.header("Set-Cookie", `session=${token}; HttpOnly; Path=/; SameSite=Lax; Secure`);
  return { user: publicUser(user) };
});
 
app.api("POST", "/api/logout", async (req, res) => {
  if (req.user) destroySession(req.user.id);
  res.header("Set-Cookie", "session=; HttpOnly; Path=/; Max-Age=0");
  return { ok: true };
});

Use HttpOnly cookies (JS cannot read them) with Secure + SameSite; never store the token where client JS can exfiltrate it.

3. Seed the user into an auth atom

So components render the right state on first paint, hydrate __user into an atom. The cleanest path is to read it during hydration; in app code you seed an auth atom from the server's req.user:

00000000001
2
3
// atoms/auth.ts
import { atom } from "ekko:rune/mimir";
export const userAtom = atom({ key: "auth:user", default: null });   // persist:false for sensitive data → set explicitly

On a dynamic/shell route (not a cached static page), seed it per request:

00000000001
2
// a per-request page's ssr() can include the user (shell route)
export function ssr() { return { title: "Dashboard", __atoms: { "auth:user": currentUserForRequest() } }; }

Do not seed the user into a cached static page's __atoms, the HTML is shared across users. Use a dynamic/shell route for authenticated pages, or render a neutral page and load the user after hydration via GET /api/me. See Mimir → SSR & hydration.

4. Components read the user

00000000001
2
3
4
5
6
7
import { useAtomValue } from "ekko:rune/mimir";
import { userAtom } from "../atoms/auth";
 
export function AccountMenu() {
  const user = useAtomValue(userAtom);
  return user ? <span>Hi, {user.name}</span> : <a href="/login">Sign in</a>;
}

(For in-app navigation use <Link>; here /login could be a real navigation either way.)

5. Guard authenticated routes

Two layers:

00000000001
2
// server-side: register a client guard so the router redirects before rendering
app.page("/dashboard", Dashboard, { page: "dashboard.tsx", guard: { redirect: "/login" } });

00000000001
2
3
4
5
6
// in-page: gate on the atom (defence in depth)
export default function Dashboard() {
  const user = useAtomValue(userAtom);
  if (!user) return <RedirectToLogin />;   // or render a prompt
  return <RealDashboard user={user} />;
}

And reject unauthenticated API calls:

00000000001
2
3
4
app.api("GET", "/api/secret", async (req, res) => {
  if (!req.user) { res.status(401); return { error: "unauthorized" }; }
  return getSecretFor(req.user);
});

6. The `GET /api/me` pattern (for cached pages)

For pages that are cached and shared, render them neutral and fetch the user after hydration:

00000000001
useEffect(() => { fetch("/api/me").then(r => r.ok ? r.json() : null).then(setUser); }, []);

00000000001
app.api("GET", "/api/me", (req) => req.user ?? { user: null });

This keeps the cached HTML user-neutral while still personalising the UI once JS runs.

Security checklist

[ ] HttpOnly, Secure, SameSite cookies; tokens never readable by client JS.
[ ] Validate and authorize on the server in every protected API route (req.user check).
[ ] Do not seed user data into cached static pages.
[ ] Scope the app's permissions (net only to your auth/DB host, etc.).
[ ] Rotate/expire sessions server-side; logout destroys the session.

On this page

1. Middleware attaches req.user 2. Login / logout API routes 3. Seed the user into an auth atom 4. Components read the user 5. Guard authenticated routes 6. The GET /api/me pattern (for cached pages)Security checklist