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)

Static assets

Images, fonts, SVGs, downloadable files, anything you serve verbatim, go in static/ and are exposed under a URL prefix. This is separate from the client bundle (which is generated and served at /_ekko).

Configure the static directory

00000000001
2
3
4
const app = createApp({
  static: "./static",       // the folder on disk
  staticPrefix: "/assets",  // the URL prefix (default is "/static")
});

Now a file at static/logo.svg is served at /assets/logo.svg, and static/diagrams/architecture.svg at /assets/diagrams/architecture.svg.

Referencing assets

In markup and SCSS, reference the URL, not the disk path:

00000000001
<img src="/assets/logo.svg" alt="Logo" />

00000000001
2
@font-face { font-family: "Inter"; src: url("/assets/fonts/Inter.woff2") format("woff2"); }
.hero { background-image: url("/assets/hero.jpg"); }

In Markdown (e.g. these docs), an image points at the same prefix:

00000000001
![architecture](/assets/diagrams/architecture.svg)

SVG diagrams

SVG is the ideal format for diagrams in docs: it is text (diffs nicely, lives in git), scales crisply, and is small. Put .svg files in static/diagrams/ and reference them by URL. To read well on both light and dark themes, design the SVG with theme-neutral colours (mid-tone strokes/text plus an accent) since an <img> cannot inherit your CSS variables. The diagrams in these docs are built exactly this way.

Caching

Static assets are served by the app; for production you typically let nginx (in front) add cache headers, or rely on stable filenames. Unlike the hashed client chunks (which are immutable and cached forever), a static/logo.svg keeps its name, so version it in the filename (logo.v2.svg) or set appropriate cache headers if you update it often.

The bundle vs static, two different things

	Client bundle (`/_ekko`)	Static (`/assets`)
Source	generated by `ekko build --client`	files you put in `static/`
Contents	hashed JS chunks + manifest	images, fonts, svg, downloads
Caching	immutable, forever	your choice (often via nginx)
You reference it	never directly (server emits tags)	by URL in markup/SCSS/markdown

Do not put source images in /_ekko; do not expect static/ files to be hashed. They are separate systems.

Shipping static files

static/ is part of your app bundle (package.include lists static/**/*), so it ships to production with everything else. No CDN is required; the app serves them. You can of course put a CDN in front for scale, but it is not part of the basic deploy.

Favicons and OG images

Common static assets:

static/
  favicon.svg        → /assets/favicon.svg   (linked via createSEO favicon config)
  favicon.ico        → /assets/favicon.ico
  og.png             → referenced in og.image for link previews
  fonts/Inter.woff2  → @font-face in your SCSS

Wire favicons through createSEO({ favicon: { svg: "/assets/favicon.svg", ico: "/assets/favicon.ico" } }) (see SEO).

Next: putting it on the internet, Production deploy.

On this page

Configure the static directory Referencing assets SVG diagrams Caching The bundle vs static, two different things Shipping static files Favicons and OG images