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 , 3. Layouts

The layout is the chrome around every page, header, navigation, footer, theme toggle, that persists across client navigations. We will flesh out the root layout and add a theme toggle (which we will wire to state in the next step).

The root layout

pages/layout.tsx wraps every page via the layouts option in createApp. It receives children (the current page):

00000000001
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
// pages/layout.tsx
import { Link } from "ekko:rune/router";
import ThemeToggle from "../components/ThemeToggle";
 
export default function RootLayout({ children }: { children: any }) {
  return (
    <div className="app">
      <header className="topbar">
        <Link href="/" className="brand">📝 Notes</Link>
        <nav>
          <Link href="/">All</Link>
          <Link href="/notes/new">New</Link>
          <ThemeToggle />
        </nav>
      </header>
      <main className="container">{children}</main>
      <footer className="foot">Built with ekko:rune</footer>
    </div>
  );
}

Because the layout is outside the page component, it does not unmount on navigation, the header and footer stay mounted while the page swaps. That is what makes navigation feel instant and lets state held in the layout (or in atoms it reads) persist.

A theme toggle component (stubbed for now)

00000000001
2
3
4
5
// components/ThemeToggle.tsx
export default function ThemeToggle() {
  // we will wire this to a Mimir atom in the next step
  return <button className="theme-btn" title="Toggle theme">🌓</button>;
}

The layout tree (for later)

createApp({ layouts }) takes a tree keyed by path segment, so you can give different sections different chrome. The root key is "":

00000000001
2
3
4
layouts: {
  "": { layouts: [{ render: RootLayout }] },
  // "admin": { layouts: [{ render: AdminLayout }] }, // would wrap /admin/* pages
}

For Notes one root layout is enough; the full nesting model is in Layouts.

Error and not-found pages

Two more convention pages round out the chrome:

00000000001
2
3
4
// pages/error.tsx
export default function ErrorPage() {
  return <main className="container"><h1>Something went wrong</h1></main>;
}

00000000001
2
3
4
5
// pages/not-found.tsx
import { Link } from "ekko:rune/router";
export default function NotFound() {
  return <main className="container"><h1>404</h1><p>No such page. <Link href="/">Home</Link></p></main>;
}

Wire them in server.tsx:

00000000001
2
3
import ErrorPage from "./pages/error";
import NotFound from "./pages/not-found";
const app = createApp({ /* ... */ error: ErrorPage, notFound: NotFound });

See Error & not-found.

Styling the chrome

00000000001
2
3
4
5
6
.topbar { display:flex; align-items:center; justify-content:space-between;
  padding: 12px 24px; border-bottom: 1px solid var(--border); }
.topbar nav { display:flex; gap:14px; align-items:center; }
.brand { font-weight:700; color:var(--text); text-decoration:none; }
.theme-btn { background:none; border:1px solid var(--border); border-radius:8px; padding:4px 8px; cursor:pointer; }
.foot { text-align:center; color:var(--muted); padding: 24px; }

Run it

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

Navigate between / and a note: the header/footer stay; only the <main> content changes. The theme button does nothing yet, that is the next step.

Next: make the toggle (and the notes) real with state, 4. State with Mimir.

On this page

The root layout A theme toggle component (stubbed for now)The layout tree (for later)Error and not-found pages Styling the chrome Run it