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 , forms

Forms in rune are plain controlled React, with two rune-specific upgrades: drafts in atoms (so they survive navigation), and submission to a same-process API route.

A controlled form

00000000001
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
import { useState } from "@ekko/react";
 
export default function Contact() {
  const [form, setForm] = useState({ name: "", email: "", message: "" });
  const set = (k: string) => (e: any) => setForm(f => ({ ...f, [k]: e.target.value }));
 
  async function submit(e: any) {
    e.preventDefault();
    const res = await fetch("/api/contact", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(form),
    });
    if (res.ok) setForm({ name: "", email: "", message: "" });
  }
 
  return (
    <form onSubmit={submit}>
      <input value={form.name} onChange={set("name")} placeholder="Name" />
      <input value={form.email} onChange={set("email")} placeholder="Email" type="email" />
      <textarea value={form.message} onChange={set("message")} placeholder="Message" />
      <button type="submit">Send</button>
    </form>
  );
}

Use useState for a form that should reset when you leave; use an atom for a draft that should survive a navigation (or a reload, with a session):

00000000001
2
3
// atoms/contact.ts
import { atom } from "ekko:rune/mimir";
export const contactDraft = atom({ key: "contact:draft", default: { name: "", email: "", message: "" } });

00000000001
2
3
4
import { useAtom } from "ekko:rune/mimir";
import { contactDraft } from "../atoms/contact";
 
const [form, setForm] = useAtom(contactDraft);   // survives navigation; with a session, reloads too

Mark the atom persist: false if a reload should clear the draft.

The API handler , validate, then act

00000000001
2
3
4
5
6
7
8
app.api("POST", "/api/contact", async (req, res) => {
  const b = await req.json() ?? {};
  if (typeof b.name !== "string" || !b.name.trim()) { res.status(400); return { error: "name required" }; }
  if (typeof b.email !== "string" || !b.email.includes("@")) { res.status(400); return { error: "valid email required" }; }
  saveMessage({ name: b.name.slice(0, 120), email: b.email.slice(0, 200), message: (b.message ?? "").slice(0, 5000) });
  res.status(201);
  return { ok: true };
});

Always validate on the server (client validation is UX, not security). See Validation & options.

Showing submission state

Track the request with local state (or atoms if other components care):

00000000001
2
3
4
5
6
7
8
9
const [status, setStatus] = useState<"idle" | "sending" | "ok" | "error">("idle");
 
async function submit(e: any) {
  e.preventDefault();
  setStatus("sending");
  const res = await fetch("/api/contact", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(form) });
  setStatus(res.ok ? "ok" : "error");
}
// render: status === "sending" ? <Spinner /> : status === "ok" ? <p>Thanks!</p> : ...

Server-rendered, progressively enhanced

Because the page is server-rendered, the form is visible and meaningful before JS loads. After hydration, the onSubmit handler takes over for the fetch-based submit. For a no-JS fallback, point the <form action> at an API route and handle a normal POST there too, the same handler can serve both.

Warn about unsaved changes

Mark the draft dirty and guard the unload:

00000000001
2
3
4
5
useEffect(() => {
  const onUnload = (e: BeforeUnloadEvent) => { if (isDirty(form)) { e.preventDefault(); e.returnValue = ""; } };
  window.addEventListener("beforeunload", onUnload);
  return () => window.removeEventListener("beforeunload", onUnload);
}, [form]);

See Guards & redirects for the in-app navigation case.

On this page

A controlled form Drafts that survive navigation The API handler , validate, then act Showing submission state Server-rendered, progressively enhanced Warn about unsaved changes