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)

Reading and writing

Three hooks cover every component interaction with an atom: useAtom (read + write), useAtomValue (read-only), and useSetAtom (write-only). Outside React, the mimir store offers get/set/reset.

`useAtom` , read and write

Coming from React useState? useAtom is the same API. It returns the exact same [value, setValue] tuple, setValue takes a value or an (prev) => next updater, and it triggers a re-render, just like useState. The only differences: the atom is declared once, outside the component (so the state is shared across components and survives navigation/reload when persist: true), and you pass that atom to the hook:

00000000001
2
3
4
5
6
// React: state is local to this component, lost on unmount
const [count, setCount] = useState(0);
 
// Mimir: same shape, but `countAtom` is defined elsewhere and shared/persisted
const countAtom = atom({ key: "count", default: 0 });   // once, module scope
const [count, setCount] = useAtom(countAtom);            // same [value, setValue] as useState

Returns [value, setValue], like useState, but the state lives in the store:

00000000001
2
3
4
5
6
7
8
9
10
11
import { useAtom } from "ekko:rune/mimir";
import { themeAtom } from "../atoms/theme";
 
function ThemeToggle() {
  const [theme, setTheme] = useAtom(themeAtom);
  return (
    <button onClick={() => setTheme(theme === "dark" ? "light" : "dark")}>
      Theme: {theme}
    </button>
  );
}

Reading subscribes this component to the atom: when anyone sets themeAtom, every component using it re-renders with the new value. There is no Provider and no prop drilling, distant components stay in sync because they read the same store slot.

Updater functions

setValue accepts a value or an updater (prev) => next, use the updater when the new value depends on the old:

00000000001
2
3
const [count, setCount] = useAtom(countAtom);
setCount(5);                 // set directly
setCount(c => c + 1);        // derive from previous (safe under rapid updates)

`useAtomValue` , read-only

When a component only reads (it never writes), useAtomValue returns the value directly. It also accepts a selector (derived state):

00000000001
2
3
4
import { useAtomValue } from "ekko:rune/mimir";
 
const theme = useAtomValue(themeAtom);     // just the value
const total = useAtomValue(cartTotal);     // a selector works too

It subscribes the same way useAtom does, the component re-renders when the value changes.

`useSetAtom` , write-only

When a component only writes and does not need to re-render on changes (a button buried in a toolbar), useSetAtom returns just the setter. The component does not subscribe, so it will not re-render when the atom changes elsewhere, a small but real performance win for write-only widgets:

00000000001
2
3
4
5
6
import { useSetAtom } from "ekko:rune/mimir";
 
function AddButton() {
  const setCart = useSetAtom(cartAtom);
  return <button onClick={() => setCart(items => [...items, newItem])}>Add</button>;
}

useSetAtom only accepts an atom (not a selector), you cannot set derived state.

Choosing a hook

You need to...	Use
Read and write, re-render on change	`useAtom`
Read only, re-render on change	`useAtomValue`
Read derived state	`useAtomValue(selector)`
Write only, no re-render	`useSetAtom`

Immutability

Treat atom values as immutable. To update an object or array, produce a new value rather than mutating the old one, Mimir compares with Object.is, so a mutated-in-place object looks unchanged and will not notify subscribers:

00000000001
2
3
4
5
6
7
8
// ✗ mutates in place; Object.is sees the same reference; no update
setCart(items => { items.push(newItem); return items; });
 
// ✓ new array; subscribers notified
setCart(items => [...items, newItem]);
 
// ✓ new object
setPrefs(p => ({ ...p, density: "compact" }));

Outside React , the `mimir` store

For logic that is not a component (an event handler in a module, a startup routine, an API-driven update), use the store directly:

00000000001
2
3
4
5
6
7
import { mimir } from "ekko:rune/mimir";
import { themeAtom } from "../atoms/theme";
 
mimir.get(themeAtom);              // read
mimir.set(themeAtom, "light");     // write (notifies subscribers)
mimir.set(themeAtom, t => /* ... */);  // updater form
mimir.reset(themeAtom);            // back to the atom's default

set/reset notify subscribers and dependent selectors exactly as the hooks do, so a non-component write still re-renders the components that read the atom.

No update when nothing changed

set and reset short-circuit when the next value is Object.is-equal to the current one, no notification, no re-render. This keeps updates cheap and avoids spurious renders when you "set" a value to what it already was.

Next: computing values from atoms, Selectors.

On this page

useAtom , read and write Updater functions useAtomValue , read-only useSetAtom , write-only Choosing a hook Immutability Outside React , the mimir store No update when nothing changed