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)

Asgard integration

@ekko/asgard is the EkkoJS component suite: buttons, inputs, data tables, dialogs, a docking system, a Markdown renderer with syntax highlighting, and a docs shell. It pairs naturally with rune, the docs site you are reading is a rune app rendering Asgard's MarkdownRenderer and TreeView inside a docs shell. This page shows how to wire it in.

Add it

Declare it in ship in ekko.json:

00000000001
2
3
4
5
"ship": {
  "@ekko/asgard": "^1.0.0",
  "@ekko/react": "^19.0.0",
  "@ekko/react-dom": "^19.0.0"
}

Then import components and the theme:

00000000001
2
3
import { Button, TextBox, MarkdownRenderer, TreeView } from "@ekko/asgard";
import { ThemeProvider } from "@ekko/asgard";
import { themes } from "@ekko/asgard/theme";

Theming Asgard

Asgard components read a theme object (not your CSS variables). Wrap a subtree in ThemeProvider with a theme:

00000000001
2
3
4
5
6
import { ThemeProvider } from "@ekko/asgard";
import { themes } from "@ekko/asgard/theme";
 
<ThemeProvider theme={themes.nord}>
  <Button variant="filled">Save</Button>
</ThemeProvider>

To match your site's light/dark choice, drive the ThemeProvider from your theme atom:

00000000001
2
3
4
5
6
7
8
import { useAtomValue } from "ekko:rune/mimir";
import { themeAtom } from "../atoms/theme";
import { brandLight, brandDark } from "../lib/theme";   // your Asgard Theme objects
 
function Themed({ children }: { children: any }) {
  const theme = useAtomValue(themeAtom);
  return <ThemeProvider theme={theme === "light" ? brandLight : brandDark}>{children}</ThemeProvider>;
}

This works, but on its own it means maintaining a SCSS palette and an Asgard Theme object and keeping them in sync by hand — the source of the classic "themed buttons, white page" bug. The next section removes the duplication.

Theme your page from the same theme: `<ThemeCssVars />`

ThemeProvider themes Asgard components, not your own markup (the Task-299 trap). Instead of a second SCSS palette, drop <ThemeCssVars /> inside the provider — it mirrors the active Asgard theme onto :root as --ekko-* CSS custom properties, so your own CSS themes from the same object and re-themes on every toggle. Render it once in the root layout:

00000000001
2
3
4
5
6
7
8
9
10
11
12
13
14
import { ThemeProvider, ThemeCssVars, themes } from "@ekko/asgard";
import { useAtomValue } from "ekko:rune/mimir";
import { themeAtom } from "../atoms/theme";
 
export default function Themed({ children }: { children: any }) {
  const mode = useAtomValue(themeAtom);                    // "dark" | "light" — a Mimir atom
  const theme = mode === "light" ? themes.githubLight : themes.githubDark;
  return (
    <ThemeProvider theme={theme}>
      <ThemeCssVars />                                      {/* mirrors `theme` onto :root as --ekko-* */}
      {children}
    </ThemeProvider>
  );
}

Then style your page from those variables — including the page background, which is exactly what the signoff validator checks (a fully themed page, not a white page with themed widgets on top):

00000000001
2
3
body  { background: var(--ekko-background-primary); color: var(--ekko-text-primary); }
.card { background: var(--ekko-background-elevated); border: 1px solid var(--ekko-border-default); }
a     { color: var(--ekko-accent-primary); }

Common tokens: --ekko-background-{primary,secondary,tertiary,elevated}, --ekko-text-{primary,secondary}, --ekko-border-{default,focus,divider}, --ekko-accent-{primary,secondary}. Need the map server-side? themeToCssVars(theme) returns it; applyThemeToRoot(theme) is the imperative escape hatch.

No-FOUC: apply the dark/light class before first paint with the no-FOUC script from Dark mode, and keep the choice in the themeAtom (it survives navigation). <ThemeCssVars /> re-applies the matching --ekko-* values on the client whenever the atom changes.

See Theming for the atom + toggle, and Dark mode for the full light/dark recipe.

Rendering Markdown (how these docs work)

Asgard's MarkdownRenderer turns a Markdown string into themed elements with syntax-highlighted code:

00000000001
2
3
4
5
6
7
import { MarkdownRenderer } from "@ekko/asgard";
 
<MarkdownRenderer
  markdown={doc.markdown}
  codeColorMap={codeColorMap(theme)}            // token colours for code blocks
  onLinkClick={(href) => router.navigate(href)} // keep in-app links client-side
/>

Note onLinkClick: routing Markdown links through router.navigate keeps doc-to-doc navigation on the client (no reload), the same rule as everywhere else (see Navigation).

A docs shell

The sidebar nav, breadcrumb, and content layout you see here are built from Asgard's TreeView (the nav), Breadcrumb, and SDiv (themed scroll regions), wrapped in a ThemeProvider. The pattern: a DocsShell component takes a nav tree and the current page's content, renders the sidebar + content + table of contents, and is itself wrapped in the site-aware theme. You feed it the generated docsData (nav + per-page markdown) from your content pipeline.

SSR considerations

Some Asgard components read the DOM on render (canvas-based ones, drag-and-drop). Render those client-only (after mount) and show a placeholder during SSR, the same mounted pattern you use for any non-SSR-safe component:

00000000001
2
3
const [mounted, setMounted] = useState(false);
useEffect(() => setMounted(true), []);
return mounted ? <DataTable {...props} /> : <span>Loading…</span>;

Prose, buttons, inputs, and the Markdown renderer SSR fine; gate only the genuinely DOM-dependent ones.

When to use Asgard vs plain SCSS

Plain SCSS , content sites, marketing, simple forms. Lighter, full control, no component theme to sync.
Asgard , dashboards and docs that want data tables, dialogs, trees, a docking workspace, or a Markdown

renderer out of the box. You trade the two-declarations sync for a lot of finished UI.

Next: eliminating the theme flash, No-FOUC.

On this page

Add it Theming Asgard Theme your page from the same theme: <ThemeCssVars />Rendering Markdown (how these docs work)A docs shell SSR considerations When to use Asgard vs plain SCSS