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)

Guards and redirects

Sometimes a navigation should not proceed as-is: an unauthenticated user hitting /dashboard should be sent to /login, a renamed page should redirect, or a half-filled form should warn before you leave. rune handles these with route guards, server redirects, and before-unload rules.

Route guards (client redirect rules)

A route can carry a guard in its meta. When you register the route, the guard is serialized into the client route table (__routes[].guard), so the client router can redirect before rendering the guarded page:

00000000001
2
3
4
app.page("/dashboard", Dashboard, {
  page: "dashboard.tsx",
  guard: { redirect: "/login" },   // if the guard fails, go here
});

The guard's redirect is the destination the router sends the user to when the route should not be shown. Combine it with an auth atom: the guard names the fallback, your app decides (from state) whether to apply it. A common pattern is to check an auth atom in the page/layout and navigate("/login") when it is empty, the guard's redirect is the declarative companion the router knows about up front.

Server-side redirects

For redirects that must happen on the server (SEO-friendly 301/302, moved pages, canonical hosts), handle them in an API route or middleware and send a redirect response:

00000000001
2
3
4
5
app.api("GET", "/old-path", (_req, res) => {
  res.status(301);
  res.header("Location", "/new-path");
  res.send("");
});

Or register middleware that inspects the request and short-circuits with a redirect for a class of URLs (see Middleware).

Conditional rendering vs redirecting

For UI-level gating you do not always need a redirect, you can render different content based on an atom:

00000000001
2
3
4
5
6
7
8
import { useAtomValue } from "ekko:rune/mimir";
import { userAtom } from "../atoms/auth";
 
export default function Dashboard() {
  const user = useAtomValue(userAtom);
  if (!user) return <LoginPrompt />;     // render a prompt instead of navigating away
  return <RealDashboard user={user} />;
}

Use a guard/redirect when the URL itself should change (so the back button and shareable links behave correctly); render conditionally when you just want to swap the content in place.

Back-button rules and before-unload guards

The router config (toClientConfig) carries two advanced controls baked into the page as __routerConfig:

backRules , declarative rules for what the browser Back button should do for certain paths: match a

path (by string or regex) and either goTo a specific route or skip the entry. Useful for flows where "back" should not return to an intermediate step (e.g. a payment confirmation).

beforeUnload , guards that run before a navigation/unload, so you can warn the user about unsaved

changes.

00000000001
2
3
4
5
6
7
// conceptual: warn before leaving a dirty form
const dirty = useAtomValue(formDirtyAtom);
useEffect(() => {
  const onBeforeUnload = (e: BeforeUnloadEvent) => { if (dirty) { e.preventDefault(); e.returnValue = ""; } };
  window.addEventListener("beforeunload", onBeforeUnload);
  return () => window.removeEventListener("beforeunload", onBeforeUnload);
}, [dirty]);

The router's beforeUnload config is the framework-level hook for the in-app navigation case (the beforeunload event covers hard reloads/closes).

Choosing the right tool

You want to...	Use
Send unauthenticated users away from a page	a route `guard: { redirect: "/login" }` + an auth atom
301/302 a moved or canonical URL	a server redirect (API route / middleware)
Show a different UI without changing the URL	conditional rendering on an atom
Control what Back does in a flow	router `backRules`
Warn about unsaved changes	a before-unload guard

Next: generating routes from data, Programmatic routes.

On this page

Route guards (client redirect rules)Server-side redirects Conditional rendering vs redirecting Back-button rules and before-unload guards Choosing the right tool