What is rune

ekko:rune is the application framework that ships inside the EkkoJS runtime. Where the runtime gives you a fast, secure JavaScript/TypeScript engine with a batteries-included standard library, rune is the layer on top that knows how to build and serve a web application: routing, server-side rendering, hydration, state, layouts, an API surface, SEO, and a production build pipeline.

It is imported like any other standard-library module:

rune is part of the runtime, the same way ekko:fs or ekko:net are.

Coming from elsewhere? What's different in Ekko

If you have written web apps in the broader JS ecosystem, a few things work differently here, by design:

• ESM only, no require. Everything is an ES module. There is no require() and no CommonJS.
• ekko: prefixes for built-ins. Standard-library and framework modules are imported by their

ekko: name (ekko:rune, ekko:rune/router, ekko:fs), not from a package folder.

• Import code without the extension. Your own modules are imported as ./pages/about, not

./pages/about.tsx. Ekko owns resolution and rejects extensioned code specifiers. See Why extensionless?.

• Input handlers receive the value, not an event. @ekko/asgard inputs pass the new value straight to

onChange: write onChange={(v) => setName(v)}, not onChange={(e) => e.target.value}. This is intentional. See Forms.

• Read the body with await req.json(). Async, content-type-independent, single-use accessors (the

WHATWG Request interface): await req.json() / await req.text() / await req.bytes(). req.body is a ReadableStream. See Request & response.

• req.query is the raw query string. Parse it with URLSearchParams; it is not a pre-parsed object.

The rest of this section explains the model behind these choices.

A whole application in one process

A rune app is a single EkkoJS process started from one entry file, conventionally server.tsx. That process does everything a typical web stack splits across several services:

You still put nginx in front for TLS in production (see Production deploy), but the application itself is one binary and one process.

The shape of a rune project

my-app/
  server.tsx          # entry: builds the app, registers pages + APIs, starts the server
  ekko.json           # project config: name, type "run", permissions, dependencies
  pages/              # one module per route (default export + optional ssr())
    index.tsx         #   -> /
    about.tsx         #   -> /about
    blog/[slug].tsx   #   -> /blog/:slug
    layout.tsx        #   the root layout (shell)
    not-found.tsx     #   the 404 page
    error.tsx         #   the error page
  components/         # reusable UI
  atoms/              # Mimir atoms (shared, navigation- and reload-tolerant state)
  lib/                # plain modules (config, helpers)
  styles/             # SCSS compiled at server start
  static/             # files served verbatim (images, fonts)
  .ekko/build/        # generated by `ekko build --client` (client bundle + manifest)

The Getting Started and Tutorial sections walk through each of these. The short version:

1. pages/*.tsx define your routes and their UI.
2. server.tsx wires them up and calls app.start().
3. ekko build --client compiles the browser bundle.
4. ekko run server.tsx serves it.

Server first, then client

The defining behaviour of rune is the handoff between server and client:

1. First request , the server renders the matched page to HTML (with React's renderToString), wraps

it in your layout, injects styles and a small hydration payload, and returns a complete document. The user sees content immediately, and crawlers get real HTML.

2. Hydration , the browser loads one small module bundle that attaches React to the server-rendered

markup and reads the embedded state. The page becomes interactive.

3. Navigation , from then on, clicking an in-app link swaps the page component on the client. No full

reload, no white flash, and any state held in Mimir atoms is preserved.

This is covered in depth in The rendering pipeline and Server-Side Rendering.

What rune is not

• It is not a static-site generator. Pages are rendered by a running server (and cached); you can add

static export patterns, but the model is a live SSR server.

• It is not tied to a node_modules tree. Dependencies (like @ekko/react and @ekko/asgard) come

from the EkkoJS package store and ekko.json, not npm.

• It does not require a separate API framework. API routes live in the same app.

Next: Philosophy, the principles that shape every API in rune.