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)

Configuration

A rune app is configured by ekko.json at the project root. It declares the project's identity, its entry point, the packages it ships, an import map, and, crucially, the permissions it needs. JSONC is supported (comments and trailing commas are fine).

A real rune-app `ekko.json`

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
{
  "name": "@ekko/rune-site",
  "version": "1.0.0",
  "type": "rune",                   // a full-stack Rune app (SSR + React + Mimir)
  "entry": "server.tsx",            // the file `ekko run` starts
 
  // import map: rewrite specifiers to packages from the store
  "imports": {
    "react": "@ekko/react",
    "react-dom": "@ekko/react-dom",
    "react-dom/server": "@ekko/react-dom/server",
    "react/jsx-runtime": "@ekko/react/jsx-runtime"
  },
 
  // capabilities the app may use (deny-by-default; see Permissions)
  "permissions": { "fs": true, "net": true, "env": true },
 
  // runtime dependencies, resolved from the EkkoJS store
  "ship": {
    "@ekko/asgard": "^1.0.0",
    "@ekko/react": "^19.0.0",
    "@ekko/react-dom": "^19.0.0"
  },
 
  // what to include when this project is packaged
  "package": {
    "include": ["pages/**/*", "components/**/*", "atoms/**/*", "lib/**/*",
                "styles/**/*", "static/**/*", "content/**/*", ".ekko/build/**/*"],
    "exclude": ["stdout.txt", "stderr.txt"]
  }
}

Field reference

Identity

Field	Meaning
`name`	Package name (scoped `@scope/name` or plain).
`version`	Semver.
`type`	`"run"` for an app, `"lib"` for a library, also `tool`, `gui`, `tui`, `test`.
`description`, `license`, `repository`, `readme`	Metadata.
`minEkko`	Minimum runtime version.

Entry & modules

Field	Meaning
`entry`	The file `ekko run` executes (e.g. `server.tsx`).
`imports`	An import map: rewrite a bare specifier to a package. This is how `import "react"` becomes `@ekko/react`, so the whole React ecosystem points at EkkoJS's React.
`exports`	For `type: "lib"`, the public entry points (`"."` , `"./sub"`).

Dependencies

Field	Meaning
`ship`	Runtime deps included with the published package.
`build`	Build-only deps (not shipped).
`peer`	Deps the consumer must provide; this package shares the consumer's single instance (how `@ekko/react-dom` shares one React with your app).

ekko.lock records the resolved versions and where each came from (the store, or a local .ekl file).

Permissions

00000000001
2
3
4
5
6
7
8
9
"permissions": {
  "fs": true,                  // or "./data/**" or ["./data/**", "./static/**"]
  "net": true,                 // or "localhost:*" or ["api.example.com"]
  "env": true,                 // or ["PORT", "API_KEY"]
  "sys": true,                 // OS / CPU info
  "ffi": true,                 // load native libraries
  "child_process": true,       // spawn processes
  "worker": true               // threads
}

Anything declared here is granted without a --allow flag. Scoped grants restrict to paths/hosts/vars. Full treatment in Permissions.

Packaging

package.include / package.exclude are glob lists controlling what ends up in the published/packed artifact. A rune app includes its pages, components, atoms, lib, styles, static, content, and the prebuilt .ekko/build (so production does not rebuild the client).

CLI flags vs `ekko.json`

Permissions can come from either place. During development you might run:

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

For a deployed service, declaring them in ekko.json keeps the systemd ExecStart short and the grants versioned with the code. The two are additive; the runtime grants the union.

Workspaces

A monorepo ekko.json can declare a workspace with members and a map of package names to folders. The EkkoJS package store resolves cross-member imports without publishing. rune apps work the same inside a workspace; the docs site you are reading lives in such a layout (ekko-lib/*).

Next: the security model, Permissions.

On this page

A real rune-app ekko.json Field reference Identity Entry & modules Dependencies Permissions Packaging CLI flags vs ekko.json Workspaces