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)

SCSS

You style a rune app by importing stylesheets. Write .scss (or .css) files and import them from your components; the build compiles the SCSS, bundles it, records it in the manifest, and rune injects it into every page's <head> on the server-rendered first paint. There is no compileSass call to wire up and no <style> string to assemble by hand.

How it works

Import the stylesheet once, typically from your root layout so it applies everywhere:

00000000001
2
3
4
5
6
// pages/layout.tsx
import "../styles/global.scss";   // compiled, bundled, and injected into <head> by the build
 
export default function RootLayout({ children }: { children?: any }) {
  return <div className="app-shell">{children}</div>;
}

That is the whole wiring. A plain import "./x.scss" is a side-effect import: it ships that stylesheet to every page that includes it. Plain .css files work the same way, the Sass step is simply skipped.

Hot reload under `ekko dev`

ekko dev watches your stylesheets. Editing a .scss/.css file reconverts and rebundles it and reloads the page automatically, with no server restart. (A production build, ekko build --client, compiles and hashes the stylesheets into the client output.) See The dev loop.

Component-scoped styles: CSS Modules

For class names that cannot collide, name the file *.module.scss (or .module.css) and use a default import. You get back a map of your class names to collision-proof scoped names:

00000000001
2
3
4
5
6
// components/Button.tsx
import s from "./Button.module.scss";   // s = { button: "a1b2_button", icon: "a1b2_icon", ... }
 
export default function Button({ children }: { children?: any }) {
  return <button className={s.button}>{children}</button>;
}

00000000001
2
3
// components/Button.module.scss
.button { padding: 10px 18px; background: var(--accent); &:hover { filter: brightness(1.08); } }
.icon   { width: 1rem; height: 1rem; }

Scoping is automatic and per-file (a .button here never clashes with a .button elsewhere), and the scoped names are computed identically on the server and in the client bundle, so the SSR markup matches hydration exactly. composes: joins names within the same file. Reach for modules when you want local styles; reach for a global sheet for design tokens, resets, and typography.

Why a bundled stylesheet (and SSR-first)

The compiled CSS is delivered as a <link rel="stylesheet"> emitted into the server-rendered HTML, so the page is styled on first paint with no flash of unstyled content, and the stylesheet is content-hashed and cacheable. (Theme flashing is a separate concern, handled by the no-FOUC script, see No-FOUC.)

Structure your stylesheet

A typical global.scss:

00000000001
2
3
4
5
6
7
8
9
10
11
// 1. design tokens as CSS custom properties (light + dark)
:root  { --bg:#f7f9fc; --text:#10151c; --accent:#5e81ac; /* ... */ }
.dark  { --bg:#0d1117; --text:#e6edf3; --accent:#88c0d0; /* ... */ }
 
// 2. base / reset
* { box-sizing: border-box; }
body { margin:0; background:var(--bg); color:var(--text); font-family: Inter, system-ui, sans-serif; }
 
// 3. components, all reading the tokens
.btn { background: var(--accent); color:#fff; border:0; border-radius:8px; padding:8px 14px; }
.card { background: var(--bg); border:1px solid var(--border); border-radius:12px; }

Everything reads var(--token), so flipping the .dark class restyles the whole app at once. See Theming.

SCSS features

You get the SCSS you expect, nesting, variables, @mixin/@include, @use/@import of partials, functions like color-mix (via CSS), and math.

Static CSS and assets

Fonts, images, and any static CSS you do not import go in static/ and are served at your staticPrefix (commonly /assets). Reference them in your SCSS or markup by that URL:

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

Generating CSS dynamically (escape hatch)

When you need CSS that is not known at build time (a theming server, tooling), call the ekko:ssr/css toolchain directly: compileSass, transform, minify, and cssModules, the same engine the import pipeline uses. For anything authored as a file, prefer the imports above, they are simpler and give you SSR-first delivery for free.

Next: the theme system, Theming.

On this page

How it works Hot reload under ekko dev Component-scoped styles: CSS Modules Why a bundled stylesheet (and SSR-first)Structure your stylesheet SCSS features Static CSS and assets Generating CSS dynamically (escape hatch)