#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, andfor-ofloops that build known arrays. - Deterministic built-ins such as
Math,Object,Array,JSON,String,Number,Boolean,parseInt, andparseFloat. .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