#Krate Native (Experimental)
Build a desktop app from a Krate project - TSX UI in a system webview, host code in Go or TypeScript.
Experimental. Krate Native is experimental and under active development.
krate native init,check,dev,build(also--release),profile,package,sign,notarizeandkeygenanddoctorwork today. Names, options and the SDK may change between releases, without a deprecation period. Linux is the most tested platform. The CI native job also runs the shell, the plugin and packaging tests on macOS and Windows; what each feature has been tested with on each OS is in the compatibility matrix, and manual-only checks (real key presses, tray clicks, notarization) are listed as limits there.
Krate Native compiles a Krate app into a desktop app. The UI is TSX shown in the system webview. Code that must run in the native process, such as file access, a database or the operating system, is host code: Go files, or TypeScript functions you mark. The UI imports host code and calls it like an async function.
There is no server in a native app, so there is no SSR: every route is prerendered at build time.
- Getting started -
krate native initandkrate native build, and what a build produces. - Host code - the six ways to mark host code, their precedence, conflicts, inline function rules and the native target's restrictions.
- Go host code - call exported Go functions, streams and signals from the UI.
- Host runtimes - run TypeScript host code on Node, Bun, Deno or scriptc, islands, release bundling.
- Build functions - run a function at build time and bake its result into the app.
- The app directory and app.json - the output of a build and the manifest the shell reads.
- Development -
krate native dev, hot reload and browser mode. - Native SDK: data and system - app directories, files, SQLite, key-value storage, secrets and permissions.
- Native SDK: windows and desktop - windows, dialogs, clipboard, menus, tray, shortcuts and notifications.
- Native SDK: OS integration - badge and progress on the app icon, displays, power and idle, launch at login, the system theme and crash reports.
- Camera, microphone and location - app-controlled permissions for getUserMedia, getDisplayMedia and geolocation, OS consent and screen sources.
- Views and split panes - several webviews in one window, draggable dividers, per-view scopes and view-to-view messages.
- Files and drag and drop - file associations in the installers, opening the files an app is launched with, and the paths of dropped files.
- Web contents - print and PDF, find in page, zoom, capturing a view, downloads and cookies.
- Accessibility - what the shell guarantees to screen readers and keyboard users, and what custom title bars, menus and dialogs need.
- Remote content - web pages in views and windows with their own storage, an origin allowlist, request rules, user agent, proxy, certificates and logins, and no access to the app.
- Release builds - one executable per platform, SDK shaking, derived permissions, per-window scopes and profile-guided builds.
- Native plugins - reusable native capabilities as a Go
package with a manifest, generated TypeScript and declared permissions;
native.pluginsturns one on. - Packaging -
krate native package: installers and archives for macOS, Windows and Linux, icons and Windows resources. - Signing and notarization -
krate native signandnotarize. - Stores and universal apps - one macOS app for arm64 and Intel, Flatpak, Snap, the Mac App Store and the Microsoft Store.
- Updates - in-app updates with signed update files.
- Memory - memory profiles, shared web process, tray-style background mode and measured numbers.
- Benchmarks - cold start, idle memory and size against Electron and Tauri, and how to reproduce them.
- Testing your app -
krate native testand the@krate/app/drivermodule: drive pages, host calls and native events from Node tests, headless in CI. - Migrating from Electron - concepts, a full API
mapping, a worked port (
examples/native-from-electron), security, packaging, testing and what is different. - Migrating from Tauri - commands, events,
capabilities, plugins,
tauri.conf.json, sidecars, the updater and bundler targets.
#Quick start
// krate.config.ts
import { defineConfig } from "@krate/core";
export default defineConfig({
native: {
appId: "com.acme.app",
productName: "Acme",
window: { width: 1280, height: 800 },
},
});krate native checkkrate native check loads the config, decides which modules and functions are
host code, reports conflicts and native-target errors, and prints the host
modules it found.
#The native config block
| Key | Default | Notes |
|---|---|---|
appId |
none | Reverse-DNS id such as com.acme.app |
productName, version |
none | version is semver |
platforms |
windows, macos, linux |
|
icons |
none | Path of the source icon |
window |
1280 x 800, resizable: true, titleBar: "native" |
titleBar is native, hidden or none, with transparent, backdrop, vibrancy, titleBarOverlay and trafficLightPosition next to it (Window chrome); permissions narrows the main window's page; keepAlive: true keeps the app running with no window open, for tray apps (background mode); `contextMenu: "default" |
permissions |
no restriction | An optional allowlist of SDK permission names. A build derives the permissions the code needs, writes them to app.json, and fails (KR7210) if one is not listed. Unknown names fail the config check |
deepLinks |
none | URL schemes without :// |
fileAssociations |
none | File types the app opens: ext (without the dot), name, mime, role (editor or viewer), icon. See Files |
host |
runtime: "quickjs" |
runtime is quickjs, node, bun, deno or scriptc; scriptc needs experimental.scriptc: true; islands maps a package to node, bun, deno or quickjs |
release |
compile: "auto", pgo: "native.pgo" |
compile is auto, always or never (release builds); pgo is the CPU profile krate native profile writes and --release uses |
bundle |
none | macos.category, windows.publisher, windows.installer (msix or nsis), windows.webview2 (download, embed, fixed or none) with windows.webview2Path, linux.formats (deb, rpm, appimage) |
updater |
none | url (https, may contain {target}, {version}, {channel}) and publicKey, both required; optional channel, maxStarts, healthTimeout, confirm (see Updates) |
Unknown keys inside the block warn like the other config blocks. The top-level
hostFunctions and hostDirs lists mark host code; see
Host code.
Last updated: 2026-11-17
Contributors: Noinkin