Documentation
Docs
Introduction
Getting Started
Tutorial: build an app
Core Concepts
Routing
Server-Side Rendering
Mimir, state management
Pages & Layouts
API Routes
Styling & Theming
Building & Deploying
API Reference
Guides
Recipes
FAQ (use cases)
Reference , ekko:rune
The application framework module. Import:
createApp(options) → app
Creates the application. See The application for the narrative.
Options
| Option | Type | Default |
|---|---|---|
port | number | 3000 |
host | string | "0.0.0.0" |
manifest | object | null | null |
layouts | object | null | null |
notFound | Component | null |
error | Component | null |
ssr | "eager" | "background" | "lazy" | "eager" |
lang | string | "en" |
static | string | – |
staticPrefix | string | "/static" |
tls, http2 | – | – |
maxBodySize, maxWsMessageSize | number | – |
seo | object | – |
Returns an app with:
| Method | Signature | Notes |
|---|---|---|
page | (path, component, meta?) → app | Register a route. meta: page, title, head, ssr, ttl, tags, guard. |
pages | (dir, components, metas) → app | Bulk register via scanRoutes. |
api | (method, path, [opts], handler) → app | Register an API route. |
use | (middleware) → app | Add middleware (runs every request). |
layout | (fn) → app | Set a single root layout (alt. to layouts). |
invalidate | (pathOrTag) → void | "*" all; /path; else tag. |
start | () → { server, url, stop, invalidate, cache } | Begin listening. |
renderToString | (element) → string | The active SSR renderer. |
htmlShell | (opts) → string | Assemble a document. |
resolvePageAssets | (pageKey, prefix?) → assets | Resolve a page's chunks from the manifest. |
app.page(path, component, meta?)
component is the page module (with default + optional ssr) or a component. meta:
| Key | Meaning |
|---|---|
page | manifest page key (client chunk). |
title | default <title>. |
head | extra <head> HTML. |
ssr | per-route strategy override. |
ttl | cache lifetime (seconds; 0 = no expiry). |
tags | cache tags for group invalidation. |
guard | { redirect } client redirect rule. |
app.api(method, path, [opts], handler)
method ∈ GET|POST|PUT|DELETE|PATCH. Handler (req, res); a returned value is auto-sent (object→JSON,
else text). Throwing → 500 { error }. Declaring methods for a path auto-adds 405 for the others. See
API routes.
app.invalidate(pathOrTag)
"*", clear all + re-render every static SSR route."/path", clear + re-render that route."tag", clear + re-render every cached route carrying the tag.
app.start() → handle
Begins listening; mounts /_ekko (client bundle), the HMR socket, API routes, page handlers; eagerly
renders eager routes; schedules background routes. Returns { server, url, stop(), invalidate, cache }.
scanRoutes(dir = "pages") → Route[]
Scans a directory and returns sorted routes. Each Route:
| Field | Type |
|---|---|
pattern | string (/blog/:slug) |
file / pageKey | string (manifest key) |
dynamic | boolean |
catchAll | boolean |
priority | 0 static · 1 dynamic · 2 catch-all |
Name rules: [p]→:p, [...r]→*r, (g)/→stripped, index→segment root. Skips convention files and
*.test.*. See File-based routing.
readManifest(path?) → manifest
Reads .ekko/build/manifest.json (or path). Returns { hydrate, pages, chunks, styles, routes }. Falls
back to { hydrate: null, pages: {}, chunks: [] } if absent. See The manifest.
resolvePageAssets(manifest, pageKey, prefix = "/_ekko/") → assets
Resolves a page's client assets. Returns { modules, modulepreload, pageFile, styles } (dedup'd). Used
internally to emit <script>/modulepreload/CSS tags.
createStyleCollector() → collector
A small helper to collect <style>s by id during render (add(id, css), getStyles(), reset(), has(id)),
for styled-component-style collection.
cssModule(path)
Compile/import a CSS module by path (delegates to the runtime).
Next: ekko:rune/router.