#Release builds, derived permissions and PGO
krate native build --release links one executable per platform with only the SDK areas the app uses, derives permissions, and supports PGO and window scopes.
Experimental. Part of Krate Native.
krate native build produces an app directory that the prebuilt krate-shell
runs. krate native build --release produces one executable per platform
instead: the platform layer, the scheme handler, the SDK areas the app reaches,
the app's Go host code (registered in process, no child process), the
QuickJS host only if the app has TypeScript host code, and the built UI, all in
one file.
krate native build --release # this machine
krate native build --release --target windows/amd64,darwin/arm64,linux/arm64| Flag | Meaning |
|---|---|
--release |
Link executables. Needs Go on PATH (see compile modes). |
--target <os>/<arch> |
windows, darwin (or macos) and linux, with amd64 or arm64. Repeat the flag or separate targets with commas. Every target is built with CGO_ENABLED=0, so one machine builds all of them. Default: this machine. |
--out <dir> |
Output directory. Default dist-native. |
--layout shell|executable |
For plain krate native build (without --release). An app with Go host code builds as one executable, like --release, when Go is installed (Go is needed to compile that code anyway): one process instead of the shell plus a Go host child, which saves the child's runtime (about 10 MB). --layout shell keeps the prebuilt-shell layout with the Go host child; --shell <path> does too. krate native dev always runs the shell and the child. |
Output:
dist-native/
linux-amd64/Acme one executable per target: <os>-<arch>/<productName>[.exe]
windows-amd64/Acme.exe built with -H windowsgui (no console window)
linux-amd64/host/ compiled node, bun, deno or scriptc host children, when the app has them
report.json permissions with their sites, linked SDK areas, sizesreport.json lists each target with its binary path (relative to the output
directory) and its host children; krate native package reads it to find the
payload. A Windows executable carries the icon, version information and a
DPI-aware manifest: the build writes rsrc_windows_<arch>.syso next to the
generated main from native.icons and the app metadata, and the Go linker
picks it up for that target only. With --package, the build packages every
--target after linking (see Packaging).
The executables are built with go build -trimpath -ldflags "-s -w" (plus
-H windowsgui on Windows), and -pgo=<file> when a profile
exists. They run in a window like the shell does; --browser serves the app on a
loopback port behind a session token instead (the same protocol as
krate-shell --browser), --addr picks the address,
and --version prints the product name and version. Set KRATE_CPUPROFILE=<file>
to write a CPU profile when the process exits.
#What the build generates
The build first runs the normal native build into .krate/native/release/stage
(the same UI, host bundle and manifest as the app directory), then packs that
directory into one zip archive and generates a tiny main package:
// Code generated by krate. DO NOT EDIT.
package main
import (
_ "embed"
"runtime"
glue0 "example.com/acme/.krate/native/src/lib" // generated glue of the Go host code
"github.com/kratejs/krate/packages/native/scheme"
"github.com/kratejs/krate/packages/native/shell"
)
//go:embed app.zip
var appZip []byte
func init() { runtime.LockOSThread() }
func main() {
shell.Main(shell.MustZipFS(appZip), func(r *scheme.Registry) {
glue0.Register(r)
})
}The archive is embedded with go:embed and served from memory. One archive
instead of an embed.FS of the directory, because go:embed rejects the
tasks/[id]/index.html file names dynamic routes produce, and because the
archive keeps the assets compressed. Its app.json has no gohost section: the
Go host code is linked in and registered before the first call.
Where the main package lives depends on the app:
- With Go host code it is
.krate/native/release/pkginside the project's own Go module, so the Go host packages link directly. The build uses a copy of the project'sgo.modandgo.sum(go build -modfile) completed with the native module's dependencies, so your own files are not touched. (With an activego.work, the workspace is used as it is: rungo mod tidyfor the native module's dependencies.) - Without Go host code it is a module of its own,
.krate/native/release/mod, that requiresgithub.com/kratejs/krate/packages/native. Inside the Krate repository the requirement is areplacetopackages/native. Outside it, the requirement is the module version that matches the compiler:vplus the compiler's version (krate --version; every release tagspackages/native/v<version>). The module's own requirements and checksums are embedded in the compiler. A development build of the compiler has no version: the build fails with KR7213 unlessKRATE_NATIVE_VERSIONnames a released version, orKRATE_NATIVE_DIRpoints at a checkout ofpackages/native.
#Compile modes
native.release.compile decides what --release produces:
| Value | Behavior |
|---|---|
auto (default) |
Link executables when go is on PATH; otherwise build the prebuilt-shell layout (dist-native/<os>-<arch>/<productName> plus app/, or just dist-native/app when no shell is found) and say so. |
always |
Link executables; without Go, fail with KR7212. |
never |
Always build the prebuilt-shell layout, as krate native build does. |
An app with Go host code always needs Go, in every mode (KR7212): the Go host is type-checked and compiled with the toolchain. A compile error in the release executable is KR7211. The report is written in every mode.
#Shaking the SDK
Each optional SDK area registers itself from a file behind a build tag
krate_no_<area>. The build works out which areas the app reaches and passes
-tags for the others, so their platform code is not linked:
| Tag | Leaves out |
|---|---|
krate_no_fs, krate_no_kv, krate_no_db, krate_no_net |
the data areas. kv imports db, so SQLite is out only when both are. |
krate_no_window, krate_no_dialog, krate_no_clipboard, krate_no_menu, krate_no_tray, krate_no_shortcut, krate_no_notify, krate_no_app |
the UI areas. tray needs menu, shortcut needs app. |
krate_no_hostjs |
QuickJS and the TypeScript host. Set whenever the app has no TypeScript host code. |
os and permission are always linked. An area is reached by an import from
@krate/app/<area> in UI or TypeScript host code, by a krate/<area>.<op>
string, or by Go host code importing .../packages/native/sdk/<area>. Ids of an
area that is not linked do not exist: a call answers not_found.
Measured sizes (linux/amd64, stripped, Go 1.26):
| App | Executable |
|---|---|
| every SDK area and QuickJS linked (no shaking) | 15.70 MB |
TypeScript host code and kv (links kv, db, SQLite) |
15.04 MB |
examples/native-tasks (Go and TypeScript host code, no SDK area) |
11.43 MB |
| Go host code only, no SDK area, no QuickJS | 8.04 MB |
the same plus @krate/app/tray (links tray, menu) |
+ 0.41 MB |
The tests check that a Go-only app has no QuickJS (go version -m lists no
modernc.org/quickjs, go tool nm no jsruntime symbols) and that an app that
does not use the tray has no sdk/tray symbol.
#Shaking plugin ops
Native plugins are shaken the same way, one level
finer: a release links only the plugin ops the code reaches (an import from
krate/plugin/<name>, or a "plugin/<name>.<op>" string), generates glue for
those and defines only the permissions they need. The SDK areas a plugin's Go
code imports stay linked. A plugin with no used op is still linked (its Init
and hooks run). An app with plugins is always built as one executable and needs
the Go toolchain. report.json has a plugins list with the ops each plugin
kept and left out.
#Derived permissions
A native build works out the SDK permissions the app needs from its code and
writes exactly that list to app.json, replacing the defaults. An app that
uses no SDK id gets an empty list with "strictPermissions": true, which the
shell reads as "nothing" (without the flag an empty list means the
defaults). The analysis reads every script file
under src, the pages directory and hostDirs:
| Source | What counts | Precision |
|---|---|---|
| UI code and TypeScript host code | Named imports from @krate/app/<area> map to the ids the exported function reaches (readText needs fs:read, writeText needs fs). import * as fs counts the members used as fs.name, and the whole area if fs is used any other way. A default import, export * or import() counts as the whole area. |
Imports are read from the syntax tree. A string "krate/fs.readText" counts as that id; a string with an unknown or missing operation counts as the whole area. A call whose id is built at run time from a variable is invisible. Files that nothing imports still count. |
| Go host code | Imports of .../packages/native/sdk/<area> in the Go packages the UI imports and in their dependencies (go list -deps). |
The import decides which areas are linked, not which permissions the page gets: Go host code is trusted and never permission-gated. |
An export that reaches several permissions (the window Window class) counts
all of them; every window id shares the window permission, so this is exact in
practice. Permissions that imply others are listed once (fs covers fs:read).
#The allowlist
native.permissions in the config is an optional allowlist. When it is set,
every permission the code needs must be covered by it, or the build fails with
KR7210 naming the import site:
src/pages/index.tsx:3:1: [KR7210] readText from @krate/app/fs needs the "fs:read"
permission, which native.permissions does not allow
hint: add "fs:read" to native.permissions in the config, or remove the callThe allowlist does not widen anything: app.json always holds the derived list.
krate native build (without --release) derives and checks too; krate native dev keeps the configured list or the defaults.
#Seeing what was derived
krate native check and krate check (when the config has a native block)
print a capability report: each permission with the first sites that need it, the
linked SDK areas and the ones a release build leaves out. report.json holds the
same data for tools:
{
"appId": "com.acme.app", "productName": "Acme", "version": "1.0.0",
"layout": "executable",
"permissions": [
{"name": "fs:read", "sites": [{"file": "src/pages/index.tsx", "line": 1, "col": 1, "kind": "ui", "symbol": "readText from @krate/app/fs"}]}
],
"allowlist": ["kv", "fs"],
"areas": {"linked": ["db", "fs", "kv"], "shaken": ["app", "clipboard", "dialog", "menu", "net", "notify", "shortcut", "tray", "window"]},
"goImports": [],
"hostJs": true, "goHost": false,
"tags": ["krate_no_app", "krate_no_clipboard"],
"targets": [{"target": "linux/amd64", "binary": "linux-amd64/Acme", "size": 15040000}]
}kind is ui, host (a TypeScript host module) or go. layout is
executable, or app-dir when no executable was built.
#Per-window scopes
native.window.permissions narrows what the page of the main window may use to a
list that must be a subset of the app's permissions. An empty list leaves the page
nothing. The window.open option of the SDK does the same for windows opened at
run time:
import { open } from "@krate/app/window";
await open({ path: "/preview", permissions: ["kv"] });A window opened without the option inherits the scope of the window that opened
it, and an explicit list must be a subset of the opener's, so a narrow window
cannot open a wide one (it fails with permission_denied). Go host code is not
affected.
Plugin ops are checked the same way, against their plugin:<name>.<permission>
(a host signal when the page subscribes).
The check runs on every UI call, against the window or view the call came from.
The platform layer tags every request with the webview that made it (on Linux
WebKitGTK's webkit_uri_scheme_request_get_web_view, on macOS the webView
argument of startURLSchemeTask, on Windows the WebView2 that raised
WebResourceRequested), and the shell maps that webview to its window and scope.
The x-krate-window header that page script can set is ignored in a native
window, so a scoped page cannot claim another window's id. A request from a
webview the shell cannot place gets an empty scope: it can use no SDK id.
The shell still opens a scoped window at a URL with a __krate_win query
parameter and injects a small script into every HTML page that keeps the id in
sessionStorage and sets it as the client's window id. In a native window that
only keeps the id across reloads and released windows; the header it feeds is not
trusted.
Browser mode (krate native dev --browser) is the exception: there are no native
webviews to bind requests to, so the header is the identity and a script in a
tab can send another window's id. Scopes there narrow what a window's own code does
by accident; they are not a boundary.
A scope limits what a window's code may ask the host to do. It does not isolate the window's origin: every window and view shares the
krate://apporigin, so pages of different scopes can read each other'slocalStorageand cookies. Do not load content you do not trust into a window and rely on its scope alone. The views page covers scopes of views.
#Profile-guided optimization
krate native profile # build, run, use the app, close it
krate native build --releasekrate native profile builds the app (a release executable when Go is available,
the prebuilt-shell layout otherwise), runs it with KRATE_CPUPROFILE set, and
copies the CPU profile to native.release.pgo (default native.pgo in the
project root) when the app exits. Use the app the way users do: open the windows,
call the host functions that matter, then close the window or press Ctrl-C
(a killed process writes no profile; on Windows close the window). --browser
runs the app in browser mode and prints its URL; --out <file> writes the profile
elsewhere (--memory measures memory instead; see Measuring memory). Commit the file: every later --release build finds it and passes
-pgo=<file> to go build, typically a few percent faster at the cost of a
longer compile. A configured native.release.pgo that does not exist is a note,
not an error. Without a profile nothing changes.
#Measuring memory
krate native profile --memory [dir] [--idle 30s] [--out dist-native]--memory builds the app (a release executable with the dev control channel, or
the prebuilt-shell layout without Go), runs it and samples every process it owns:
the shell, the Go host child, JavaScript host children and the webview's own
processes. Each sample reports PSS and private dirty memory per role, next
to a floor (a blank one-line page, same shell and window size, no host code),
and their difference. PSS counts a shared page once, split between the processes
that map it; private dirty is memory only that process holds. Summed resident size
counts shared WebKit libraries once per process and is not used.
Samples: after the load event plus 5 s (afterLoad), after --idle more
(afterIdle, default 30 s; 0s skips it), after navigating through every
prerendered route three times (afterStorm), and with the window hidden
(hidden, only for an app that links the window SDK area). The table is
printed and stored as the memory section of <out>/report.json: per sample, per
role pss and privateDirty in bytes for app, floor and appMinusFloor.
Linux reads /proc/<pid>/smaps_rollup. macOS reports phys_footprint (what
Activity Monitor shows) for both numbers and Windows reports private bytes; there
the webview's processes are found through WebKit and WebView2 APIs and some may be
missing (the report's notes say which). The same data is available from a
running --dev shell as the memory control command and GET /__krate/dev/memory.
Last updated: 2026-11-17
Contributors: Noinkin