Krate Docs

#Compile-Time Evaluation

How Krate evaluates known values, static lists, local helpers, and pure expressions during the build.

Krate evaluates expressions during the build whenever their inputs are known and they cannot change at runtime. The result is written as static HTML with no hydration binding for that value.

const stats = { open: 2, closed: 5 };
const total = stats.open + stats.closed;
const entries = Object.entries(stats);

return (
  <section data-total={total}>
    <p>{entries.map(([name, count]) => `${name}: ${count}`).join(", ")}</p>
  </section>
);

Both the attribute and the text above are folded at build time. The page emits no runtime expression for either value.

#What is evaluated

  • Literals, arrays, objects, templates, operators, and conditionals.
  • Computed object keys ({ [KEY]: value }, { [${a}-${b}]: value }, { [Kind.Primary]: value }) whose key folds to a string or number. A key that does not fold (it reads a signal, or something only known at request time) leaves the whole object to the runtime; the key is never replaced by the expression's spelling.
  • Module constants and imported constants that resolve to literal values.
  • Component locals, including destructuring.
  • Local helper functions whose bodies stay within the pure subset.
  • Bounded for, while, and for-of loops that build known arrays.
  • Deterministic built-ins such as Math, Object, Array, JSON, String, Number, Boolean, parseInt, and parseFloat.
  • .map() and .flatMap() callbacks with inline functions, named local functions, destructured parameters, defaults, rest parameters, and index/array parameters.

#Static lists

A list whose source and callback are known at build time is flattened directly into static slots:

const items = [{ id: 1, title: "Home" }, { id: 2, title: "Docs" }];

<ul>
  {items.map(({ id, title }) => <li key={id}>{title}</li>)}
</ul>

Both .map() and .flatMap() flatten this way. This emits the two <li> elements and no list runtime, list markers, or kbindList call. A list is kept dynamic only when its source is signal-backed or otherwise unknown at build time.

#JSX held in constants and props

An array or object that holds JSX is rendered to HTML at build time wherever a component reads it, whether the constant is declared in the module (before or after the component) or inside the component:

const sections = [
  { id: "terms", title: "Terms", body: (<><p>Be kind.</p></>) },
  { id: "privacy", title: "Privacy", body: <p>We keep little.</p> },
];

<main>
  {sections.map(s => <section key={s.id}><h2>{s.title}</h2>{s.body}</section>)}
</main>

The same goes for a JSX element passed as a prop (<Hero intro={<p>Welcome</p>} />, read as props.intro or a destructured intro), including arrays and conditionals of JSX, when the receiving component is in another module and when it has state. The server HTML contains the markup, and hydration keeps it.

A constant is inlined only when every name it uses means the same thing where it is read. If a component parameter, a local, a .map() callback parameter or a signal hides one of those names, the constant is not inlined and its content is filled in when the page hydrates. A let is treated like a const only while nothing assigns to it. A JSX prop that reads the caller's own values is evaluated in the caller's scope, so a callee parameter with the same name does not change it.

#Element types held in variables

<Tag> where Tag is a variable renders the element it names when the build can fold the value to one tag:

const Wrap = "section";

function Box({ as: Tag = "div", children }) {
  return <Tag>{children}</Tag>;
}

<Wrap><Box as="h2">Title</Box></Wrap>

A string constant, a prop the caller passes, a parameter default, and a condition on those all fold. A tag that depends on a signal, on a value only known at request time, or on an omitted prop with no default does not: the build stops with a KR8320 error instead of emitting an empty placeholder. Pass the tag as a string, render each case as its own element, or put the component in a *.runtime.tsx file, where the tag is an ordinary JavaScript value at request time.

#Namespace members as tags

A member tag of a namespace import renders the component the member names, whatever the case of the namespace and however many barrel files sit between:

import * as ui from "./ui"; // ui/index.ts: export { Button } from "./Button"

<ui.Button>Save</ui.Button>

The build follows export { X } from, export { default as X } from, export * and export * as group from to the function that declares the component, and <ui.group.Input /> resolves the same way. A member that does not exist, or is not a function component, stops the build with a KR8321 error that names the tag, instead of emitting an unknown element. Members of an npm React library are mounted as islands, as named imports are.

#Module values changed by top-level code

A module-level value is not always its initializer. Top-level statements that change it run at build time, in source order, before anything reads it:

const squares = [];
for (let i = 0; i < 3; i++) squares.push(i * i);
let total = 0;
for (const s of squares) total += s;

<ul>{squares.map((s) => <li>{s}</li>)}</ul> // three items
<p>{total}</p>                                // 5

Assignments, ++, property writes, push and other method calls, loops, branches, Object.assign, and calls to functions of the module that do any of these are run, in the module that declares the value and in the modules it is imported from. Code that only reads a value (console.log(cfg), window.__cfg = cfg) or that runs later (a callback passed to addEventListener) does not affect it, and a module with no such statements folds from its initializers exactly as before.

When a statement cannot be run at build time (it reads the browser, the clock or an imported function, or sorts or reverses in place), the values it may have changed stay unknown instead of keeping their initial value. A component that hydrates reads them in the browser, where the hydration script replays the statement. A component rendered at build time (@static, @server) has no run time, so the build fails with KR8322. Make the top-level code plain, or compute the value in one expression.

#Setup code in the browser

A top-level call, new expression or property assignment of a client module that starts from a binding imported from a package (dayjs.extend(...), extend(...) from @krate/three, THREE.ColorManagement.enabled = ...) is package setup code: it also runs in the browser, once per page load, before the page hydrates, as it would when the module loads.

import dayjs from "dayjs";
import relativeTime from "dayjs/plugin/relativeTime";
import { extend } from "@krate/three";
import { OrbitControls } from "three/examples/jsm/controls/OrbitControls.js";

dayjs.extend(relativeTime);
extend({ OrbitControls });

Statements of imported modules run before those of the modules that import them, and a layout's before its page's. Statements that start from your own code (a local function or a binding imported from one of your modules, such as Dialog.Trigger = Trigger) are not setup code and are not run this way; nor are statements of server, static and runtime modules or "use server" modules. A setup statement that reads a binding the page script cannot include (one that only a side effect initializes) is left out with the warning KR8302; move it into onMount or a component. An error thrown by setup code is logged and does not stop the page from hydrating.

#Values the build cannot know

A value that is not known at build time never renders as its own spelling. An unresolved identifier, window.innerWidth, or a signal seeded from one renders empty in the static HTML and is filled in when the page hydrates:

const initial = window.innerWidth;
const [width] = createSignal(initial);

<p>{width()}</p> // empty before hydration, the width after

A signal seeded from a constant (const initial = 5) renders that value in every component, including components the page renders as children.

#Props

props.label is the value the caller passed. A prop the caller left out is undefined, or its default ({ label = "x" }), even when the module or the component has a constant or local with the same name:

const label = "module";

function Card({ label = "dflt" }) { return <p>{label}</p>; }

<Card /> // <p>dflt</p>

Parameters that rename or nest ({ item: { id, tags: [first, ...rest] = [] } }) bind their names by destructuring the passed props, at build time and in the hydration code. A signal passed to a parameter the build keeps destructured is read once; the build warns and suggests reading props.<name> to keep it live.

#Reactive values

A known initial value is not the same as a static value. If an expression reads a signal, the initial value is used for SSR output but the hydration binding is retained:

const [count, setCount] = createSignal(0);

<p>{count() + 1}</p>

The 0 + 1 initial is rendered on the server, then count() remains reactive after hydration.

#Purity rule

Krate does not evaluate values that depend on time, randomness, I/O, the environment, or imported executable code. Expressions using Date, Math.random, fetch, process, Intl, or locale-dependent string methods stay runtime values. This keeps builds deterministic and reproducible.

A constrained JavaScript-engine fallback handles pure built-ins that the Go constant interpreter does not model, such as new Array(...). The fallback only runs after a purity check and only when every identifier in the expression is a known local value or an allowed global.

The fallback, and the evaluation of getCollection() chains, run in a stripped-down QuickJS VM: the ECMAScript built-ins plus structuredClone and console, with no fetch, crypto, timers, process or require. In that VM localeCompare, the toLocale*String methods and Date.prototype.toString (which String(date) and template literals call) throw, so an expression that reaches them, such as a collection sorted with localeCompare, stays a run-time value instead of being folded with the build machine's locale and time zone.

#Notes

  • A local helper is folded only when its body is evaluable without side effects.
  • A loop must have a statically known bound and a pure body.
  • Unsupported or impure expressions are left to the runtime; they are never silently replaced with a partial value.
  • Static .map() output still honors child component hydration and props.

Last updated: 2026-11-17

Contributors: Noinkin