#Build Functions
Run a function once during the native build and bake its result into the app with @build or //krate:build. Rules for literal arguments and plain-data results.
Experimental. Part of Krate Native, which is under construction.
A build function is a host function that runs once while the app is built. Its result is baked into the app: UI code that calls it gets the value at prerender time, so the value is in the HTML and no host call happens at run time. It is opt-in, because the compiler cannot prove that a function has no side effects.
#Marking one
TypeScript: the @build decorator, or the string "@build" as the first
statement of the body (the same two forms as @host). A build function is host
code, so the rules of host code apply; it can sit in
a .host.ts module or inline in a UI module.
// src/lib/build.host.ts
@build
export function buildInfo(label: string): string {
return `${label} ${new Date().toISOString().slice(0, 10)}`;
}Go: the //krate:build directive in the doc comment of an exported function
that returns one value (and optionally an error).
// Edition is evaluated while the app is built.
//
//krate:build
func Edition(name string) string { return "Krate " + name + " edition" }UI code calls them like any host function, but the call is replaced by the value:
import { buildInfo } from '../lib/build.host';
import { Edition } from '../lib/tasks.go';
export default function Home() {
return <p>{buildInfo('Built')} - {Edition('Tasks')}</p>;
}The call is a plain synchronous value, not a promise; await buildInfo('x')
still works. Build functions are not registered with the host, so they are not
in the host bundle or in app.json.
#Arguments are literals
Every argument must be a literal: a string, number, boolean, null, or an
array or object of those. Each distinct call with literal arguments gets its
own baked value, so greet("ann") and greet("bob") are evaluated
separately. Anything else (a variable, an expression) is KR7240. Using the
function without calling it (passing it, aliasing it, a namespace import,
export *) is KR7241.
#How they are evaluated
- TypeScript build functions are bundled with esbuild together with the
modules they import and run in a bare QuickJS VM: the ECMAScript built-ins,
no
fetch, timers, file system,process, or the SDK. Methods that depend on the locale or time zone (toLocaleString,Date#toString, ...) throw, so the value does not depend on the build machine. Keep a module that holds build functions free of imports that need a browser or Node API (put them in their own module). A function that throws, rejects or never settles is KR7242. - Go build functions run in a small generated Go program, built inside your module with the same glue as the Go host, so arguments and results go through the normal wire conversion. This needs the Go toolchain, and only when the UI uses a Go build function (KR7245 if the program cannot be built).
#What can be baked
Plain data only: strings, finite numbers, booleans, null, arrays and plain
objects. At most 8 MiB of JSON, nested at most 512 levels, arrays of at most
1,000,000 elements. NaN, Infinity, cycles, functions, symbols, bigint, Date,
Map, Set, binary data, class instances and promises that never settle are
KR7243. @build on a component, a generator or a stream, a default export, or
a Go function that returns a channel or nothing is KR7244.
#Calling the SDK from host code
The same @krate/app/<area> imports work in TypeScript host code. In the
webview they go over HTTP; in host code, which runs in the shell's QuickJS VM,
@krate/app finds globalThis.__krateHost.call and dispatches in-process
into the shell's registry, with no HTTP:
// src/lib/notes.host.ts
import * as kv from '@krate/app/kv';
export async function addNote(text: string) {
await kv.set('last-note', text); // in-process
}__krateHost.call(id, args), __krateHost.stream(id, args) and
__krateHost.signal(id) are the underlying primitives; call returns a
promise, stream an async iterable and signal an object with get(),
subscribe(fn) and close(). Host code is trusted: these calls are not
gated by the app's permissions (the permissions gate the UI), so a host-code
call to krate/kv.set works even when app.json does not grant kv. The
permissions derived for a release still include what host code can reach.
Go host code calls the data packages (db, kv, fs) directly; they use the
same files as the ids.
#Testing UI that calls host code
mockHost(moduleId, impl) from @krate/app/testing matches calls by module
id, the part of the id before the last dot. For import { List } from "../lib/tasks.go" the id is src/lib/tasks.List, so the module is
src/lib/tasks; for a TypeScript host module it is the path without the
extension, which keeps .host (src/lib/notes.host).
import { afterEach, expect, it } from 'vitest';
import { mockHost, resetHostMocks } from '@krate/app/testing';
import { visibleTitles } from '../src/pages/titles'; // calls List() from tasks.go
afterEach(resetHostMocks);
it('shows the titles Go returns', async () => {
mockHost('src/lib/tasks', { List: async () => [{ id: 1, title: 'mocked' }] });
expect(await visibleTitles()).toEqual(['mocked']);
});#Host calls as resources
A host call is a promise, so it fits createResource from @krate/runtime,
which integrates with Suspense boundaries:
const [tasks, { refetch }] = createResource(undefined, () => List());
// tasks() is undefined while loading; tasks.state and tasks.error report the rest.
No adapter is needed; the call carries the resource's abort signal when you
pass it as the last argument ((_, { signal }) => List({ signal })).
Last updated: 2026-11-17
Contributors: Noinkin