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)

Recipe , pagination

Paginate a list using the query string for the page number, the router to navigate, and an atom (or server-known data) for the items. This keeps pages shareable (the URL carries the state) and navigation instant.

State in the URL

The page number belongs in the query string (?page=2), not in component state, so a paginated view is shareable, bookmarkable, and survives reloads for free.

00000000001
2
3
4
5
6
7
8
9
10
import { useRouter, useSearchParams } from "ekko:rune/router";
 
export default function PostList() {
  const { navigate, path } = useRouter();
  const search = useSearchParams();
  const page = Math.max(1, Number(search.page || "1"));
  const goTo = (p: number) => navigate(`${path}?page=${p}`);   // client navigation, updates the URL
 
  // ... render the page's items + controls (below)
}

Server-side slice (cached pages per page)

If the data is server-known, you can register a static route per page number so each page of results is fully server-rendered and cached, great for SEO on a blog index:

00000000001
2
3
4
5
6
7
8
// server.tsx , one cached route per page of posts
const PAGE_SIZE = 10;
const pages = Math.ceil(allPosts().length / PAGE_SIZE);
for (let p = 1; p <= pages; p++) {
  const Comp: any = function PageRoute() { return <PostList />; };
  Comp.ssr = () => ({ title: `Blog, page ${p}`, head });
  app.page(`/blog/page/${p}`, Comp, { page: "blog.tsx", head });
}

The component reads the page from the path/query and slices allPosts(). Each /blog/page/N is its own cached, indexable URL. See Programmatic routes.

Client-side slice (live or per-user data)

For data fetched after hydration, keep the items and the page in atoms and slice on the client, or fetch the page from an API that supports ?page:

00000000001
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
const itemsAtom = atom({ key: "posts:all", default: [] as Post[] });
 
export default function PostList() {
  const items = useAtomValue(itemsAtom);
  const search = useSearchParams();
  const page = Math.max(1, Number(search.page || "1"));
  const size = 10;
  const slice = items.slice((page - 1) * size, page * size);
  const total = Math.ceil(items.length / size);
  return (
    <>
      <ul>{slice.map(p => <li key={p.id}>{p.title}</li>)}</ul>
      <Pager page={page} total={total} />
    </>
  );
}

00000000001
2
3
4
5
6
7
8
9
10
11
12
13
import { useRouter } from "ekko:rune/router";
 
function Pager({ page, total }: { page: number; total: number }) {
  const { navigate, path } = useRouter();
  const go = (p: number) => navigate(`${path.split("?")[0]}?page=${p}`);
  return (
    <nav className="pager">
      <button disabled={page <= 1} onClick={() => go(page - 1)}>← Prev</button>
      <span>{page} / {total}</span>
      <button disabled={page >= total} onClick={() => go(page + 1)}>Next →</button>
    </nav>
  );
}

Because it uses navigate, clicking a page is a client navigation: the URL updates, the list re-slices, no full reload, and any other state (filters, scroll) is preserved.

Server-paginated API (large datasets)

For datasets too large to ship to the client, paginate in the API and fetch per page:

00000000001
2
3
4
5
6
7
app.api("GET", "/api/posts", async (req) => {
  const sp = new URLSearchParams(req.query.replace(/^\?/, ""));
  const page = Math.max(1, Number(sp.get("page") || "1"));
  const size = Math.min(50, Number(sp.get("size") || "10"));
  const all = listPosts();
  return { page, size, total: all.length, items: all.slice((page - 1) * size, page * size) };
});

00000000001
2
3
useEffect(() => {
  fetch(`/api/posts?page=${page}`).then(r => r.json()).then(setResult);
}, [page]);

Choosing

Data	Approach
Server-known, SEO matters	one cached route per page (`/blog/page/N`)
Bundled/embedded, modest size	client slice from an atom, URL holds the page
Large / per-user	API with `?page`, fetch per page into an atom

That completes the Recipes, and the documentation. Browse any chapter from the sidebar, or start over with the Tutorial.

On this page

State in the URL Server-side slice (cached pages per page)Client-side slice (live or per-user data)A pager that uses the router Server-paginated API (large datasets)Choosing