Philosophy

rune is opinionated. The opinions are few, but they shape every API. Understanding them up front makes the rest of the documentation feel inevitable rather than arbitrary.

1. Server-rendered first, client-driven after

The first byte the browser receives is real, complete HTML, rendered on the server from your React tree. That gives you fast first paint, working pages without JavaScript, and correct SEO. Then a small bundle hydrates the page and the application becomes a single-page app: subsequent navigation is client-side and instant.

This is not "SSR or SPA". It is SSR then SPA, in that order, automatically. You never choose between the two; rune does the handoff for you.

2. State is islands, not a tree

Most frameworks put state in a component tree and lose it the moment you navigate or refresh. rune's state layer, Mimir, is the opposite: state lives in standalone atoms identified by a string key, outside any component. Components subscribe to the atoms they care about.

The consequences are deliberate:

• Navigation-tolerant , client-side navigation swaps the page component, but atoms persist. A theme,

a cart, a sidebar's open/closed state, all survive moving between pages.

• Reload-tolerant , with a session enabled, atoms are mirrored to IndexedDB and rehydrated after an F5.
• Server-hydratable , the server can seed atoms before rendering, and the client picks up exactly those

values with no flicker or mismatch.

Rule of thumb: if a piece of state should survive a navigation or a refresh, it belongs in an atom, not in useState. See Mimir.

3. Convention over configuration

The filesystem is the configuration. A file at pages/blog/[slug].tsx is, by its path, the route /blog/:slug. A file named layout.tsx is a layout; not-found.tsx is the 404; error.tsx is the error boundary. There is no route table to maintain, no central registry to keep in sync.

pages/index.tsx          ->  /
pages/about.tsx          ->  /about
pages/docs/[...path].tsx ->  /docs/*path   (catch-all)
pages/(marketing)/x.tsx  ->  /x            (group folder, stripped from the URL)

See File-based routing.

4. One language, one runtime, one process

The page, the layout, the API handler, the SSR logic, and the state are all TypeScript running in the same EkkoJS process. There is no serialization boundary you have to think about between "the server" and "the API", because they are the same program. Data you compute at startup (a docs index, a config object) is just a module import.

5. Secure by default

EkkoJS is deny-by-default. A rune app declares the capabilities it needs (fs, net, env, ...) in ekko.json or via --allow flags, and the runtime refuses anything outside that grant. A page cannot read arbitrary files or reach arbitrary hosts unless you allowed it. See Permissions.

6. A real build, not a dev illusion

ekko build --client produces a content-hashed, code-split, tree-shaken browser bundle (via the built-in esbuild) plus a manifest.json. The running server reads the manifest to emit exactly the right <script type="module"> and <link rel="modulepreload"> tags per page. What you run in production is what you built, no on-the-fly transpilation of client code on the prod box.

7. No magic you cannot read

ekko:rune is a single, readable JavaScript module. createApp returns a plain object with page, api, use, start. The hydration payload is a JSON <script> you can inspect in dev tools. The manifest is a JSON file. When something surprises you, you can read exactly what happened, the framework is small enough to hold in your head.

These principles recur throughout the docs. When an API seems to "just work", it is usually one of these seven at play. Next: Why rune.