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)

Installation

rune is part of the EkkoJS runtime, so "installing rune" means having ekko on your machine. There is no separate framework package to add.

Create a project

Once ekko is on your PATH, the recommended way to start a rune app is ekko init rune — it writes the correct ekko.json ("type": "rune", entry server.tsx, the React imports map) and a working starter, so you never hand-write the manifest:

00000000001
2
3
4
5
ekko init rune my-app -t asgard-minimal   # clean themed starter (recommended). Also: minimal (plain) | showcase, asgard (full demos to learn from)
cd my-app
ekko add                       # install the declared deps + write ekko.lock
ekko build --client            # generate the client bundles (.ekko/build)
ekko dev server.tsx            # watch + HMR  (or: ekko run server.tsx --allow=fs,net,env)

The rest of this guide explains what the scaffold produced and how to run it.

Prerequisites

The ekko binary on your PATH. Verify it:

00000000001
  ekko --version

A rune application depends on a few packages from the EkkoJS store, declared in ekko.json:

00000000001
2
3
4
5
6
7
  {
    "ship": {
      "@ekko/react": "^19.0.0",
      "@ekko/react-dom": "^19.0.0",
      "@ekko/asgard": "^1.0.0"     // optional: the component + docs UI library
    }
  }

These resolve from the EkkoJS package store (~/.ekko/store), not from npm. There is no node_modules directory.

Getting a project

The fastest start is to copy a rune template, a minimal project with server.tsx, a pages/ folder, a layout, a theme, and the docs pipeline already wired up. Then:

00000000001
2
3
ekko add @ekko/react @ekko/react-dom   # ensure runtime deps are in the store + lockfile
ekko build --client                    # compile the browser bundle into .ekko/build
ekko run server.tsx --allow=fs,net,env # start the server

Open http://localhost:3000.

The two commands you will use constantly

Command	What it does
`ekko build --client`	Transpiles + bundles the client code (your pages, hydration) into `.ekko/build/client/*` and writes `.ekko/build/manifest.json`. Run it whenever client-rendered code changes.
`ekko run server.tsx --allow=...`	Starts the rune server. It reads the manifest, compiles your SCSS, registers routes, and listens.

The --allow flags grant runtime capabilities. A typical rune app needs fs (read templates, SCSS, static files), net (listen and proxy), and often env (read PORT). You can also declare these in ekko.json under permissions so you do not repeat them on the command line, see Permissions.

Permissions at a glance

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

fs , read your pages, styles, and static assets.
net , bind the listening socket (and make outbound requests if your app does).
env , read environment variables such as PORT.

If you forget a needed permission, the runtime throws a clear permission error naming the capability, add it to the flag (or to ekko.json).

Editor setup

rune apps are plain TypeScript + TSX. Any editor with TypeScript support works. The ekko:* modules are ambient (provided by the runtime); your project's tsconfig and the EkkoJS type definitions make import { createApp } from "ekko:rune" type-check.

Next: build your first page in Quick start.

On this page

Create a project Prerequisites Getting a project The two commands you will use constantly Permissions at a glance Editor setup