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)

Reference , `ekko.json`

The project manifest. JSONC (comments + trailing commas allowed). See Configuration for the narrative.

Full schema

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
31
32
33
34
35
36
37
38
39
40
41
42
43
44
{
  // identity
  "name": "@scope/name",
  "version": "1.0.0",
  "type": "rune" | "web" | "run" | "lib" | "tool" | "gui" | "tui" | "test",  // web app = "rune" (NOT "run")
  "description": "...",
  "license": "MIT",
  "repository": "https://...",
  "readme": "README.md",
  "minEkko": "0.0.1",
 
  // entry & modules
  "entry": "server.tsx",
  "imports": { "react": "@ekko/react", "react-dom": "@ekko/react-dom", "react/jsx-runtime": "@ekko/react/jsx-runtime" },
  "exports": { ".": "./dist/index.js", "./sub": "./dist/sub.js" },   // type: "lib"
  "bin": { "mycli": "./dist/cli.js" },                               // type: "tool"
 
  // dependencies
  "ship":  { "@ekko/asgard": "^1.0.0" },   // runtime deps, shipped
  "build": { "typescript": "^5" },         // build-only deps
  "peer":  { "@ekko/react": "^19.0.0" },    // consumer provides; shared instance
 
  // permissions (deny-by-default)
  "permissions": {
    "fs": true | "./data/**" | ["./data/**","./static/**"],
    "net": true | "localhost:*" | ["api.example.com"],
    "env": true | ["PORT","API_KEY"],
    "sys": true, "ffi": true | ["lib.so"], "child_process": true, "worker": true
  },
 
  // packaging
  "package": { "include": ["pages/**/*","components/**/*","static/**/*",".ekko/build/**/*"], "exclude": ["*.test.ts"] },
 
  // advanced
  "native": { "linux-x64": { "lib": "lib.so.1" } },
  "publish": "public" | "private",
  "storage": "public" | "private",
 
  // run aliases: `ekko x <name>` runs the target (a store package or a file). See "Run aliases" below.
  "x": { "smtp": "@ekkojs/smtp-dev", "dev": "./scripts/dev.ts" },
 
  // workspaces (monorepo root)
  "workspace": { "members": ["packages/a"], "map": { "@org/a": "packages/a" } }
}

Field reference

Identity

Field	Notes
`name`	Scoped or plain package name.
`version`	Semver.
`type`	What the project is, which decides how it builds and runs. A web app is `"rune"` (SSR + React + Mimir, has a client bundle, `ekko dev` serves it); `"web"` is a static/client web project. `"run"` is a plain script or service with no client bundle (`ekko run entry.ts`), `"lib"` a published library, `"tool"` a CLI (uses `bin`), `"gui"`/`"tui"` desktop/terminal apps, `"test"` a test project. Building a Beacon-style app? Use `"rune"`, not `"run"` , `ekko dev` rejects `"run"` because it has no client bundle.
`description`, `license`, `repository`, `readme`	Metadata.
`minEkko`	Minimum runtime version.

Entry & modules

Field	Notes
`entry`	File `ekko run` executes.
`imports`	Import map: rewrite a specifier to a package (how `"react"` → `@ekko/react`).
`exports`	Public entry points (libraries).
`bin`	CLI commands (tools).

Run aliases (`x`)

x maps a short name to a run target, so ekko x <name> (and ekko run <name>) runs it. The target is a store package (@ekkojs/smtp-dev) or a file path (./scripts/dev.ts). Example: with "x": { "smtp": "@ekkojs/smtp-dev" }, ekko x smtp runs @ekkojs/smtp-dev.

Resolution order: the workspace x (this ekko.json, walked up from the current directory) is checked

first, then the global map in ~/.ekko/config.json (x). No match → the name resolves as usual (file, store package, or bin), so nothing breaks.

What's an alias name: a plain identifier ([A-Za-z0-9_-], no dots/slashes). File names, paths, and

scoped specs like @scope/pkg are never treated as aliases.

Relative targets in a workspace alias resolve against this ekko.json's folder, so ekko x dev works

from any subfolder. Aliases may chain to other aliases (cycles are rejected).

Managing global aliases: ekko alias list (shows workspace + global), ekko alias set <name> <target>,

ekko alias rm <name>. Workspace aliases are edited here in ekko.json.

Dependencies

Field	Notes
`ship`	Runtime deps, included when published.
`build`	Build-only deps.
`peer`	Consumer must provide; this package shares the consumer's single instance.

ekko.lock records resolved versions and each dep's source ("store" or a local .ekl).

Permissions

Deny-by-default capability grants. Values: true (blanket) or a scope (glob for fs, host:port for net, var-name list for env). See Permissions.

Packaging

package.include / package.exclude , globs controlling the published/packed artifact. A rune app includes its source folders and the prebuilt .ekko/build.

Advanced

Field	Notes
`native`	Platform-specific native artifacts.
`publish` / `storage`	Visibility / storage bucket.
`workspace`	Monorepo `members` + name→folder `map`.

A minimal rune-app `ekko.json`

00000000001
2
3
4
5
6
7
8
9
10
11
{
  "name": "my-app",
  "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": ["PORT"] },
  "ship": { "@ekko/react": "^19.0.0", "@ekko/react-dom": "^19.0.0" },
  "package": { "include": ["pages/**/*","components/**/*","atoms/**/*","lib/**/*","styles/**/*","static/**/*","content/**/*",".ekko/build/**/*"] }
}

Next: CLI commands.

On this page

Full schema Field reference Identity Entry & modules Run aliases (x)Dependencies Permissions Packaging Advanced A minimal rune-app ekko.json

Reference , ekko.json

Full schema

Field reference

Identity

Entry & modules

Run aliases (x)

Dependencies

Permissions

Packaging

Advanced

A minimal rune-app ekko.json

Reference , `ekko.json`

Run aliases (`x`)

A minimal rune-app `ekko.json`