#Migrating from Electron
Move an Electron app to Krate Native - concepts, a full API mapping table, a worked port with tests, security, packaging, debugging and what is different.
Experimental. Part of Krate Native, which is under construction. This guide describes what exists in this release. Where Krate Native has no equivalent of an Electron API, the table says so instead of suggesting a workaround that does not exist.
An Electron app is a Node.js main process, one or more Chromium renderer processes and a preload script between them. A Krate Native app is a Go shell that shows your pages in the system webview (WebKitGTK on Linux, WKWebView on macOS, WebView2 on Windows) and runs your host code (Go, or TypeScript on an embedded QuickJS) in the native process. The UI is TSX that Krate compiles; the page is plain HTML, CSS and a small signal runtime.
What carries over: HTML, CSS and the web platform your pages use, TypeScript,
npm packages that run in a browser, and the shape of your app (windows, a menu,
a tray, dialogs, files, a settings store). What does not: anything in the page
that needs Node, require, Electron's modules or a specific Chromium version.
The worked port below converts a small real Electron app,
file by file. Its Electron original and the ported app are both in the
repository: examples/native-from-electron.
#Concepts
| Electron | Krate Native |
|---|---|
Main process (main.js) |
Host code: Go files, or TypeScript marked @host or named *.host.ts (Host code, Go host code). It runs in the native process. There is no app.on('ready'); startup work runs from Go init/main code or from the first page. |
| Renderer process | A page: a route of your app, prerendered at build time and shown in the system webview. Pages are TSX (src/pages). |
Preload script and contextBridge.exposeInMainWorld |
Nothing to write. The page imports a host module and calls its functions; the compiler generates the stubs and the .d.ts types (Splitting host code from the UI). The page always runs isolated, with no Node. |
ipcMain.handle and ipcRenderer.invoke |
An exported host function and a call to it. Rejections arrive as a KrateError with a code. |
ipcRenderer.on and webContents.send (main to renderer) |
A host signal (hostSignal(), Go krate.NewSignal) for state that pages follow, a host stream (an async function*, Go <-chan T) for a sequence of values, or view.post for a one-off message to a view. |
ipcRenderer.send / ipcMain.on (fire and forget) |
A host function whose result you ignore. There is no sendSync. |
Renderer to renderer (MessageChannelMain, postMessage through the main process) |
view.post between views, or message ports (@krate/app/port). |
BrowserWindow |
A window: the first one is main, others open with open() from @krate/app/window (Go window.Open). Options: WindowOptions. |
BrowserView, WebContentsView |
A view: several webviews in one window with split panes, their own routes and per-view scopes. |
webContents |
The web contents of a view: @krate/app/page (print, find, zoom, capture), @krate/app/downloads, @krate/app/cookies. |
session |
Cookies and site data for the app's own pages (cookies); for remote pages, a partition with its own storage, user agent, proxy and request rules. |
protocol.handle, webRequest |
The app's pages are served by the shell from the app directory over a fixed scheme (krate://app, https://app.localhost on Windows). You cannot register another scheme or intercept the app's own requests. For remote pages: request rules (block, redirect, headers). |
utilityProcess.fork |
Workers: native.workers, started by name, with their own narrowed permissions. |
Child processes (child_process) |
Go host code uses os/exec; TypeScript host code on QuickJS has no child_process; use a worker or a Node, Bun or Deno host runtime. |
MessageChannelMain |
Ports, shell-backed (the engines cannot share a real MessagePort). |
app.getPath('userData') |
appDataDir() from @krate/app/os. |
electron-store or a JSON file in userData |
@krate/app/kv (a key-value store), @krate/app/db (SQLite), or files through @krate/app/fs. |
electron-builder, Forge |
krate native package (Packaging). |
electron-updater, autoUpdater |
@krate/app/updater with a signed JSON feed (Updates). |
| Playwright for Electron | krate native test and @krate/app/driver (Testing). |
#A worked port
examples/native-from-electron contains a small Electron app, Scratchpad,
and its port. The Electron version is in electron/ (pinned versions in
electron/package.json, no node_modules; run it with npm install and
npm start there). The Krate Native version is the rest of the directory. Both do the same
things:
- a window with a text area, a Settings window opened from the menu;
- an application menu with accelerators (New, Open, Save As, Settings, About);
- a tray icon with Show and Quit;
- open and save dialogs, and files read and written through them;
- a draft saved automatically to the app's data directory;
- a notification;
- a settings store (theme and font size) that the main window follows when the settings window changes it.
| Electron | Krate Native |
|---|---|
electron/main.js |
src/lib/store.host.ts (host functions and signal) and the setup code in src/pages/index.tsx |
electron/preload.js |
none |
electron/renderer/index.html, renderer.js |
src/pages/index.tsx |
electron/renderer/settings.html, settings.js |
src/pages/settings.tsx |
electron/package.json (build) |
krate.config.ts (native) |
electron/tests/app.spec.js |
tests/port.native.test.ts |
#Step 1: create the project
Start from krate native init scratchpad and add @krate/app, @krate/core
and @krate/runtime to package.json
(Getting started). The Electron package.json
fields that described the app move to the native block:
// krate.config.ts
export default defineConfig({
entry: 'src/pages/index.tsx',
pagesDir: 'src/pages',
outDir: 'dist',
native: {
appId: 'com.example.scratchpad', // build.appId
productName: 'Scratchpad', // build.productName
version: '1.0.0', // version
window: { width: 900, height: 640, resizable: true },
permissions: ['app', 'dialog', 'fs', 'kv', 'menu', 'notify', 'os:info', 'tray', 'window'],
},
});native.permissions has no Electron counterpart. It is an allowlist; see
Step 8 and Security.
#Step 2: turn ipcMain.handle into host functions
In main.js each channel is a handler registered with ipcMain.handle, and the
preload script re-exports it as a method. Draft loading and saving, and the
settings:
// electron/main.js
ipcMain.handle('draft:load', async () => { /* readFile(userData/draft.txt) */ });
ipcMain.handle('draft:save', (_event, text) => fs.writeFile(draftFile(), text, 'utf8'));
ipcMain.handle('settings:get', () => settings);
ipcMain.handle('settings:update', async (_event, patch) => { /* validate, write, broadcast */ });In Krate Native they are exported functions of a host module. A file named
*.host.ts is host code, so it runs in the native process, not in the webview:
// src/lib/store.host.ts
import { hostSignal } from '@krate/app/host';
import * as kv from '@krate/app/kv';
import * as fs from '@krate/app/fs';
export const settings = hostSignal<Settings>(defaults);
export async function updateSettings(patch: Partial<Settings>): Promise<Settings> {
await load();
const next = { ...settings.get(), ...patch };
if (next.theme !== 'light' && next.theme !== 'dark') throw new Error('theme must be light or dark');
await kv.set('settings', next);
settings.set(next);
return next;
}
export async function loadDraft(): Promise<string> {
return (await fs.exists('draft.txt')) ? fs.readText('draft.txt') : '';
}
export async function saveDraft(text: string): Promise<void> {
await fs.writeText('draft.txt', text);
}What changed:
- No registration, no channel names. The export is the API. The page imports
it (
import { saveDraft } from '../lib/store.host') and the compiler turns the import into a call to the idsrc/lib/store.host.saveDraft. - No
fsfrom Node. TypeScript host code runs on an embedded QuickJS by default, which has no Node built-ins (importingnode:fsisKR7230). The same@krate/app/fsand@krate/app/kvthe page can use also work in host code, in-process. A relative path is relative to the app data directory, sodraft.txtis Electron'spath.join(app.getPath('userData'), 'draft.txt'). If you need Node itself, setnative.host.runtimetonode,bunordeno(Host runtimes); the SDK modules are not wired into those children yet. - Settings in
kv, not a JSON file.kv.get/kv.setreplace thesettings.jsonread and write. Use@krate/app/dbif the data is relational. - Errors.
throw new Error(...)in a host function rejects the page's call, asipcRenderer.invokedoes. In a dev build the message ends with the source location ((at src/lib/store.host.ts:36:64)). Throw an object with acodeto give the page something to branch on. - Arguments are data. Functions, class instances and DOM objects cannot cross
(
KR7190). Dates,Uint8Arrays and plain objects can.
#Step 3: replace webContents.send with a host signal
Electron broadcasts the new settings to every window:
for (const win of BrowserWindow.getAllWindows()) win.webContents.send('settings', settings);and each renderer subscribes through the preload script (onSettings). In
Krate Native the host module exports a signal (above: settings) and every
page that reads it is updated when the host calls settings.set(next):
// src/pages/index.tsx and src/pages/settings.tsx
import { getSettings, settings } from '../lib/store.host';
// A host signal reads as undefined until the host has pushed its first value.
const theme = () => settings()?.theme ?? 'light';
<main data-theme={theme()}>...</main>The settings window calls updateSettings; the main window, which never asked,
changes theme. A host signal that has no value yet reads as undefined: the
first version of the port threw a TypeError on settings().theme in the page
until the value arrived, which the page-errors check of the test caught.
#Step 4: the pages
renderer/index.html and renderer.js become one TSX component. DOM code
(document.getElementById, addEventListener, textContent) becomes signals
and JSX:
const [text, setText] = createSignal('');
<textarea id="note" value={text()} onInput={(e) => edit(e.currentTarget.value)} />
<p id="status">{status()}</p>The draft is saved 300 ms after the last keystroke by the same debounce the
Electron renderer uses. A second window is a second route: src/pages/settings.tsx
is the page /settings.
#Step 5: windows, menu, tray
Electron's main.js builds these at startup. Krate Native has no ready
event, so the example does the setup once from the main page, in an effect (a Go app would do it from Go
host code, as in the Windows, dialogs and the desktop
example):
// Menu: Menu.setApplicationMenu(Menu.buildFromTemplate(...))
menu.setApp([{ label: '&File', submenu: [
{ id: 'file.new', label: 'New', accelerator: 'CmdOrCtrl+N' },
{ id: 'file.settings', label: 'Settings...', accelerator: 'CmdOrCtrl+,' },
// ...
] }]);
menu.onMenu('file.new', newNote); // template `click` handlers
menu.onMenu('file.settings', () => openWindow({ path: '/settings', title: 'Settings', width: 420, height: 280, fixed: true }));
// Tray: new Tray(nativeImage.createFromPath(...)) with setContextMenu and 'click'
fetch('/tray.png').then((r) => r.arrayBuffer()).then((png) =>
tray.set({ tooltip: 'Scratchpad', icon: new Uint8Array(png), menu: [
{ id: 'tray.show', label: 'Show' }, { id: 'tray.quit', label: 'Quit' } ] }));
tray.onEvent((e) => { /* e.kind is click, middle-click, right-click or menu; e.id is the item */ });Differences to know about:
- Menu items have an
idand the click arrives as an event (onMenu(id, fn)oronClick), not as aclickfunction in the template. There are noroleitems (role: 'quit',editMenu): add an item with its own id and callquit(). On macOS, an app menu without an Edit menu does not give you the standard editing shortcuts, so build an Edit menu from items yourself. Accelerators are writtenCmdOrCtrl+...; Electron'sCommandOrControlis not accepted on Linux and Windows. - There is one application menu for all windows (
setApp); each click event carries the id of the window it came from. - The tray icon is PNG bytes (
Uint8Array), not anativeImage. The example shipspublic/tray.pngand fetches it. On Linux the tray needs a StatusNotifier host or an XEmbed tray; without onetray.setrejects withunsupported, so the example catches it and reports it in the page. - The tray and menu belong to the app, not the page, but in this example they are
created by the main page, so reloading the main page sets them again. For a
tray app that stays alive with no window set
native.window.keepAlive(Memory). BrowserWindow'sparentandmodal,show: false,minWidthandmaxWidthandbackgroundColoroptions have no counterpart inopen(). Hide a window after opening it withhide().
#Step 6: dialogs and files without a preload bridge
The Electron renderer cannot touch the file system, so the main process shows the dialog and reads the file:
ipcMain.handle('file:open', async () => {
const { canceled, filePaths } = await dialog.showOpenDialog(mainWindow, { /* filters */ });
if (canceled || filePaths.length === 0) return null;
return { path: filePaths[0], text: await fs.readFile(filePaths[0], 'utf8') };
});In Krate Native the page may call both the dialog and the file API, and the SDK keeps it safe: a path is allowed only inside the app directories or when the user chose it in a dialog.
async function openDialog() {
const [path] = await dialog.openFile({ filters: [{ name: 'Text', patterns: ['*.txt', '*.md'] }] });
if (path) setText(await fs.readText(path)); // [] when the user cancels
}
async function saveAs() {
const path = await dialog.saveFile({ name: 'note.txt', overwrite: true }); // null when cancelled
if (path) await fs.writeText(path, text());
}dialog.openFile and saveFile grant the chosen path to the fs scope, so
readText and writeText succeed for it and reject with permission_denied
(reason: "outside_scope") for every other path outside the app directories.
That is stricter than Electron, where the main process reads whatever path the
renderer sends it. If you want Electron's shape (the page only passes a request),
put the dialog and the read in a Go or TypeScript host function; host code is
trusted and is not scoped. Filters use glob patterns (*.txt), not extensions.
Cancelling gives [] or null, not { canceled: true }.
Files the app is asked to open (double click, command line, drop on the window)
arrive through onOpenFile and onFileDrop
(Files and drag and drop); that replaces the open-file
app event and webUtils.getPathForFile.
#Step 7: notifications
const n = new Notification({ title, body });
n.on('click', () => { mainWindow.show(); mainWindow.focus(); });
n.show();becomes
await notify.send({ id: 'reminder', title: 'Scratchpad', body: '...' });
notify.onAction('reminder', '', () => main().focus()); // '' is a click on the body
Notification.isSupported() has no counterpart; call send and handle the
unsupported rejection (Linux without a notification service answers that).
Actions (actions: [{ id, label }]), urgency and replacing a notification by
sending the same id are supported. On macOS notifications need an app bundle;
krate native dev runs from a generated dev bundle for that reason.
#Step 8: permissions
The ported app uses app, dialog, fs, kv, menu, notify, tray and
window. krate native build finds that out by reading the imports and writes
exactly this list to app.json. native.permissions is only an allowlist: the
build fails with KR7210 if the code needs something the list does not name.
krate native dev and krate native test grant the list as written (or the
non-sensitive defaults when there is none), which is why fs, tray and
os:info (used by the test) are listed. Run krate native check to see which
import needs which permission. See Release builds, derived permissions.
#Step 9: tests
Electron's Playwright test launches the app and drives the renderer:
const app = await electron.launch({ args: ['.'] });
const page = await app.firstWindow();
await page.fill('#note', 'hello');tests/port.native.test.ts does the same with launch() from
@krate/app/driver, and also covers files, the menu, a second window, the tray
and the notification. Run it with krate native test (on a headless Linux
machine, xvfb-run -a krate native test). Details in Testing.
#API mapping
@krate/app/<area> is the TypeScript module, krate/<area>.<op> the SDK id
(what page.call() takes and what the permission table
lists), and the Go column is the package under
github.com/kratejs/krate/packages/native/sdk/. "None" means there is no
equivalent in this release.
#App
| Electron | Krate Native | Notes |
|---|---|---|
app.quit() |
quit() from @krate/app/app (krate/app.quit); Go app.Quit() |
|
app.relaunch() |
relaunch() (krate/app.relaunch) |
|
app.getPath('userData') |
appDataDir() (krate/os.appDataDir); Go sdkos.AppDataDir() |
Named after the appId: ~/.local/share/<id>, ~/Library/Application Support/<id>, %APPDATA%\<id>. |
getPath('cache' / 'logs' / 'temp') |
cacheDir(), logDir(), tempDir(); configDir() |
appData, home, documents, downloads, desktop, exe: none. Ask the user with dialog. |
app.getVersion(), app.getName(), app.getLocale(), process.platform, process.arch |
info() (krate/os.info): appVersion, appId, locale, os (linux, darwin, windows), arch, osVersion, hostname |
The product name is not in info(). |
app.on('ready'), whenReady |
none | Run startup code from Go host code or the first page. |
app.on('window-all-closed') |
The app quits when the last window closes; native.window.keepAlive: true keeps it running |
|
app.on('before-quit'), will-quit |
none at app level. Per window: setPreventClose(true) and onCloseRequested |
|
app.requestSingleInstanceLock(), second-instance |
Go app.SingleInstance(id, args); onSecondInstance (krate/app.events) |
TypeScript-only apps cannot take the lock directly; an app with fileAssociations takes it automatically. |
app.setAsDefaultProtocolClient, open-url |
native.deepLinks (registered by the installer); onOpenURL |
|
open-file |
native.fileAssociations; onOpenFile, openedFiles (Go app.OnOpenFile) |
|
app.setLoginItemSettings |
setLoginItem(enabled), getLoginItem() from @krate/app/login |
Needs the login permission. |
app.setBadgeCount, dock.setBadge |
setBadge(n | text), clearBadge() from @krate/app/badge |
|
win.setProgressBar |
setProgress(state, value) |
|
win.flashFrame, dock.bounce |
setUrgent(on) |
|
app.dock.hide() |
setDockVisible, setActivationPolicy from @krate/app/chrome; bundle.macos.agent |
macOS only. |
app.isPackaged |
none | |
app.commandLine.appendSwitch, GPU flags |
none | The engine is the system webview. |
#Windows and views
| Electron | Krate Native | Notes |
|---|---|---|
new BrowserWindow({ width, height, title, resizable, frame, alwaysOnTop, fullscreen, x, y }) |
open({ width, height, title, fixed, frameless, alwaysOnTop, fullscreen, position, path }) from @krate/app/window (krate/window.open); Go window.Open |
path is the route. fixed is resizable: false. titleBar, transparent, backdrop, vibrancy, permissions also exist. Always-on-top and position are ignored on Wayland. |
win.loadFile, win.loadURL('file://') |
win.navigate(path) (krate/window.navigate) |
App routes only. For a web page use @krate/app/remote. |
win.close(), show(), hide(), focus(), minimize(), maximize(), unmaximize() |
the same names on the Window object (restore() for unmaximize); main(), get(id) |
hide({ release: true }) also frees the webview. |
win.setTitle, setSize, setPosition, setAlwaysOnTop, setFullScreen |
setTitle, setSize, setPosition, setAlwaysOnTop, setFullscreen |
|
win.getBounds(), isMaximized() |
state() (krate/window.state) |
No move/resize events; read the state. |
win.on('close') with preventDefault |
setPreventClose(true) and onCloseRequested |
|
window events (focus, blur, closed) |
onEvent: close-requested, closed, focus, blur, released, restored |
|
BrowserWindow.getAllWindows() |
list() (krate/window.list) |
|
win.setMenu, setMenuBarVisibility, autoHideMenuBar |
none | One application menu for all windows. |
parent, modal, show: false, minWidth, maxWidth, backgroundColor, icon per window |
none | native.icons is the app icon. |
titleBarStyle, titleBarOverlay, vibrancy, backgroundMaterial, trafficLightPosition |
native.window.titleBar, titleBarOverlay, vibrancy, backdrop, trafficLightPosition; drag regions with -webkit-app-region: drag or data-krate-drag |
Window chrome. |
WebContentsView, BrowserView |
win.addView, setLayout, split, pane, focusView, navigateView, getView |
Views. |
screen.getAllDisplays(), getPrimaryDisplay() |
listDisplays(), primaryDisplay() from @krate/app/screen |
|
screen.on('display-added' ...) |
onDisplaysChanged |
|
| window position by display | displayOfWindow(), centerWindow() |
#Menus, tray, shortcuts, notifications
| Electron | Krate Native | Notes |
|---|---|---|
Menu.setApplicationMenu |
setApp(items) from @krate/app/menu; Go menu.SetApp |
kind: normal, check, radio, separator, submenu; disabled; checked; accelerator. No role, icon, visible, sublabel. |
MenuItem.click |
onMenu(id, fn), onClick(fn); Go menu.OnItem |
|
Menu.popup, webContents.on('context-menu') |
popup(items); setContextMenu({ mode }), onContextMenu, defaultContextItems |
Modes default, none, custom, extend. Built-in actions are ids that start with krate:. |
new Tray(image), setToolTip, setContextMenu, setTitle |
tray.set({ icon, tooltip, title, menu }), tray.remove(); events click, middle-click, right-click, menu |
icon is PNG bytes. displayBalloon, setImage alone, getBounds: none (call set again). |
globalShortcut.register |
register(accelerator, fn) from @krate/app/shortcut, returns an unregister function |
Needs shortcut. Wayland needs the GlobalShortcuts portal. |
new Notification(...) |
send({ id, title, body, icon, actions, urgency, silent, timeoutMs }), close(id), onAction(id, action, fn), onEvent |
|
Notification.isSupported() |
app.supports("notify") (krate/app.supports) |
Also "tray", "dialog", "clipboard", "shortcut", "media", "window:alwaysOnTop" and more. |
#Dialogs, clipboard, shell, files
| Electron | Krate Native | Notes |
|---|---|---|
dialog.showOpenDialog |
openFile(opts), openFolder(opts) from @krate/app/dialog; Go dialog.OpenFile |
Returns paths, [] when cancelled. multiple, filters (glob patterns), dir, title, showHidden. Grants the paths to fs. |
dialog.showSaveDialog |
saveFile({ name, dir, filters, overwrite }) |
null when cancelled. |
dialog.showMessageBox |
message({ kind, title, message, detail, buttons, default }) returns the button index; confirm(title, text) |
-1 when dismissed. No checkboxLabel. |
dialog.showErrorBox |
message({ kind: "error", ... }) |
|
clipboard.readText, writeText |
readText(), writeText() from @krate/app/clipboard |
Reading needs clipboard:read. |
clipboard.readHTML, readRTF, write({ text, html, rtf }) |
readHtml(), readRtf(), write({ text, html, rtf }) |
|
clipboard.readImage, writeImage |
readImage(), writeImage(png) |
PNG bytes, not a nativeImage. |
clipboard.availableFormats, readBuffer, writeBuffer |
formats(), readFormat(mime), writeFormat(mime, bytes) |
|
clipboard.clear |
clear() |
|
shell.openExternal |
openExternal(url) from @krate/app/os (krate/os.openExternal) |
http, https and mailto only. Needs shell:openExternal. |
shell.openPath, showItemInFolder, trashItem, beep |
none | |
fs in the main process |
Go: the standard library. TypeScript host code: @krate/app/fs (readFile, readText, readDir, stat, exists, writeFile, writeText, mkdir, remove, rename). |
The fs SDK is scoped to the app directories and dialog grants. Reads are limited to 64 MiB. |
safeStorage |
secretSet, secretGet, secretDelete from @krate/app/os |
OS credential store (Keychain, Credential Manager, Secret Service). Needs os:secrets and os:secrets.read. |
electron-store |
kv.get, kv.set, kv.delete, kv.keys |
|
better-sqlite3 |
db.exec, db.query, db.transaction from @krate/app/db |
SQLite. |
net.request, net.fetch |
fetch in the page; net/http in Go host code |
Use fetch in the page or net/http in Go host code. TypeScript host code on QuickJS has a limited API surface (KR7193 warns about APIs it lacks). The net permission is reserved. |
nativeImage |
none | Images are PNG bytes. |
#System
| Electron | Krate Native | Notes |
|---|---|---|
nativeTheme.shouldUseDarkColors, themeSource, updated |
getTheme(), setTheme("system" | "light" | "dark"), onThemeChange from @krate/app/theme |
setTheme changes native title bars and dialogs; use prefers-color-scheme in CSS for the page. |
powerMonitor (suspend, resume, lock-screen, on-battery, getSystemIdleTime) |
powerState(), idleTime(), onPower(kind, fn), onPowerEvent from @krate/app/power |
Kinds: suspend, resume, lock, unlock, ac, battery, idle, active. |
powerSaveBlocker |
preventSleep(reason, display?), allowSleep(id) |
Needs power:inhibit. |
autoUpdater, electron-updater |
check(), download(onProgress), apply(), relaunch(), update() from @krate/app/updater |
Signed feed with delta updates, staged rollouts, channels and rollback; see Packaging. |
crashReporter |
@krate/app/crash: listCrashReports, readCrashReport, deleteCrashReport, onCrash, setCrashAutoReload |
Reports are JSON files under the app's log directory. Nothing is uploaded; sending them is the app's job. |
desktopCapturer.getSources |
sources(), chooseSource(id) from @krate/app/media |
macOS and Windows list screens and windows; no engine accepts a chosen source in this release. |
systemPreferences.getMediaAccessStatus, askForMediaAccess |
osStatus(kind), osRequest(kind) |
For camera, microphone, screen and location. |
systemPreferences (other keys, accent color, animations) |
none | |
session.setPermissionRequestHandler |
onRequest(handler), getPolicy, setPolicy, native.media from @krate/app/media |
Covers camera, microphone, screen, location, notifications, clipboardRead for the app's pages. Remote pages are always denied. |
inAppPurchase, TouchBar, pushNotifications, net.isOnline |
none |
#Web contents, sessions, processes
| Electron | Krate Native | Notes |
|---|---|---|
webContents.print, printToPDF |
print(), printToPdf(opts) from @krate/app/page |
Needs page. |
webContents.findInPage, stopFindInPage |
find(text, opts), stopFind(), onFind |
|
setZoomFactor, getZoomFactor |
setZoom(f), zoom() |
|
capturePage |
capture() (PNG) |
|
webContents.executeJavaScript, insertCSS |
none | Host code cannot run script in a page. Send a signal, a stream value or a view message and let the page act. (krate native dev has a control channel for tests; it is not an app API.) |
webContents.openDevTools |
F12 or Ctrl+Shift+I (Cmd+Option+I) in dev builds; native.debug: true keeps it in a release build |
|
webContents.send |
host signal, host stream, view.post |
|
session.cookies |
list, get, set, delete, clearSiteData from @krate/app/cookies |
WebKit keeps no cookies for the app scheme, so on Linux and macOS pass an http(s) URL. |
session.on('will-download'), downloadItem |
configure, list, cancel, onEvent, onDone from @krate/app/downloads |
|
session.webRequest, protocol.handle |
remote partitions only: setRules, setUserAgent, setProxy from @krate/app/remote |
None for the app's own pages. |
session.fromPartition |
partition: "persist:name" on a remote view or window |
|
<webview>, loading a remote site |
addView, openWindow from @krate/app/remote |
The remote page gets no access to the app. |
utilityProcess.fork |
startWorker(name), native.workers |
|
MessageChannelMain |
createChannel(), transferPort(), portFromId() from @krate/app/port |
|
Offscreen rendering (offscreen: true) |
openOffscreen, captureFrame, frames from @krate/app/offscreen |
|
webContents.debugger, --remote-debugging-port |
native.automation, @krate/app/automation |
CDP on WebView2, WebKit inspector on WebKitGTK, Safari inspection on macOS. |
| Chrome extensions | native.extensions |
WebView2 and macOS 15.4 or newer only. |
ipcRenderer.sendSync, remote, @electron/remote |
none |
#Security
Electron's advice is to turn on contextIsolation and sandbox, turn off
nodeIntegration, and expose a narrow bridge. In Krate Native that is how every
page runs, and the rest differs in these ways.
- Permissions come from the code. A build reads which
@krate/app/<area>imports andkrate/...ids your UI and TypeScript host code use, and grants exactly those permissions to the pages inapp.json. Nothing in the page can ask for more at run time. In Electron the preload script decides, and nothing checks that it exposes only what the page needs. See Derived permissions;krate native checkprints a report of which import needs which permission. native.permissionsis an allowlist. The build fails (KR7210) when the code needs something outside it, so a newimportof a sensitive area (fs,clipboard:read,os:secrets.read,shell:openExternal,tray,shortcut) cannot slip in unnoticed.fsis not granted by default.- Per-window and per-view scopes.
native.window.permissions, thepermissionsoption ofopen()and ofaddView()narrow what one window's or view's page may call. The shell identifies the calling webview from the platform, not from anything the page sends, so a narrow page cannot claim a wide window's id. A window can never open a wider one. See Per-window scopes. - Origin lock. An app view is never navigated off the app origin. Web pages go
in remote views, which have their own storage, no
bridge, an empty permission scope, an origin allowlist for navigation, denied
permissions and cancelled downloads. In Electron the same page sits in the same
kind of renderer as your app and you build those rules yourself with
will-navigate,setWindowOpenHandlerandsessionhandlers. - The
fsscope. Page file access is limited to the app directories and paths the user chose in a dialog. Host code is trusted and not scoped. - Limits that remain. Every window and view of the app shares one origin, so
their
localStorageand cookies are shared and a scope is not an isolation boundary for content you do not trust. The page's Content Security Policy forbidseval. In browser mode (krate native dev --browser) scopes only catch mistakes. Go host code and TypeScript host code are not permission-gated; review them like Electron's main process.
#Packaging and updates
| Electron | Krate Native |
|---|---|
electron-builder or Forge config (build, forge.config.js) |
native in krate.config.ts: appId, productName, version, icons, bundle, deepLinks, fileAssociations, updater |
electron-builder (all targets), electron-forge make |
krate native package [--target <os/arch>] [--format <list>] |
| NSIS | bundle.windows.installer: "nsis" (needs makensis) |
| MSIX / AppX | "msix", and msix-store for the Microsoft Store |
| dmg, zip, mas | dmg (macOS only), zip, --target mas |
| deb, rpm, AppImage, snap, flatpak, tar.gz | bundle.linux.formats / --format (AppImage needs appimagetool) |
| Universal macOS build | --target darwin/universal or --arch universal |
.icns / .ico from a source image |
native.icons (one PNG; the packager writes the rest) |
| asar | none; the app directory is copied as is, or embedded in a release executable |
| Bundled Chromium and Node | none: the system webview and a Go shell. A release is one executable per platform with the app embedded; the shell binary alone is about 16 MB on Linux, 11 MB stripped (see Getting started) |
CSC_LINK, WIN_CSC_LINK, notarize |
krate native sign and notarize, KRATE_MACOS_IDENTITY, KRATE_WINDOWS_PFX, KRATE_GPG_KEY, notary credentials (Signing) |
latest.yml, electron-updater publish providers |
A JSON feed you host anywhere over https (latest-{target}.json, written by package with --update-base-url) and an Ed25519 key from krate native keygen |
| Differential updates (blockmap) | --delta-from <dir>: signed bsdiff patches against earlier releases, with fallback to the full download |
| Staged rollout | --rollout, krate native rollout; channel |
Differences to plan for:
- The webview is a system component. On Windows the installer checks for the
WebView2 Runtime and can download, embed or fix it
(
bundle.windows.webview2). On Linux the machine needs WebKitGTK 4.1 (2.40 or newer).krate native doctorreports all of this. - Code signing and the update signature are two things. The platform certificate makes the OS trust the app; the updater key makes the app trust the update. You need both, and Krate does not sign for you without your keys.
- Stores forbid self-updating. Under Flatpak, Snap, the Mac App Store and the
Microsoft Store the
updatercalls report the store's own mechanism. - Building.
krate native buildruns without a Go toolchain when a shell is available and the app has no Go host code or plugins; Go host code, plugins and--releasesingle-file executables need Go. Cross-compiling usesCGO_ENABLED=0, so you can build every platform from one machine, apart from formats that need a platform tool (dmg,makensis,appimagetool).
#Testing
| Electron with Playwright | Krate Native |
|---|---|
_electron.launch({ args }) |
launch() from @krate/app/driver; krate native test builds the app first |
app.firstWindow() |
app.page() (the main window) |
app.windows() |
app.windows(), app.views(), app.waitForView(id) |
page.fill, click, press, type |
the same names (DOM events, not OS input) |
page.locator(...).textContent() |
page.text(selector), page.value(selector) |
expect(...).toHaveText and auto-waiting |
page.waitFor(selector | predicate), poll(fn); Node's assert |
page.evaluate |
page.evaluate(fn, ...args) (the function is serialized) |
electronApp.evaluate(({ app }) => ...) |
page.call("krate/os.appDataDir"), page.call("src/lib/store.host.loadDraft"): any host function or SDK id |
Mocking dialog.showOpenDialog |
A dialog cannot be clicked; call the code behind it (the example exposes loadFile and saveFile as a test hook) |
| Clicking the menu or tray | app.emit.menu(id), app.emit.tray(kind, id), app.emit.shortcut(accelerator) |
page.screenshot() |
Not available yet |
| Test runner | Node's built-in node:test |
| Console and page errors | page.errors(), app.logs() |
Each launch() starts the real shell with fresh data, config and cache
directories, so tests never see your real settings. Input is synthesized in the
page (isTrusted is false), native dialogs and notifications are not operated,
and a notification can be asserted only as "sent" or "unsupported". CI needs a
display (xvfb-run -a krate native test on Linux; the macOS and Windows hosted
runners have one). See Testing your app.
#Debugging
| Electron | Krate Native |
|---|---|
electron . with reload |
krate native dev: hot reload of pages, in-place reload of TypeScript host code, a restart of the Go host child on .go edits |
| DevTools in each window | F12 or Ctrl+Shift+I (Cmd+Option+I on macOS), per window and per view; on in dev, off in release unless native.debug |
--inspect for the main process |
krate native dev --debug-host (Node, Bun, Deno host children); --debug-go runs the Go host under Delve (--debug-config vscode writes the launch config) |
Main-process console.log |
The terminal of krate native dev and the app log; page errors from every window are printed with the window or view id |
| Opening the app in a browser | krate native dev --browser (scopes are not a boundary there) |
| Crash reports | @krate/app/crash |
| Checking the machine | krate native doctor; the dev overlay shows build and page errors, and the dev Memory panel shows memory |
See Development.
#Things that are different
- System webviews, not one Chromium. WebKitGTK, WKWebView and WebView2 differ
in CSS and JavaScript support, in fonts and scrolling, and ship on the user's
schedule. Test on all three. Features that depend on Chromium internals
(
chrome.*APIs, some codecs, DevTools protocol access from the page) are not there. WebKit has noMessagePortsharing between webviews, which is why ports are shell-backed. - No Node in the page, and no Node by default in host code. TypeScript host
code runs on QuickJS unless you choose
node,bunordeno. Many npm packages that touchfs,pathorchild_processbelong in Go host code, in a worker or in a Node host child. - No
require, noremote, no synchronous IPC. Every host call is asynchronous. Host calls never run at build time: during prerendering a host call or signal read yields no value, and a top-levelawaitof one isKR7102. - Prerendered pages, no server. SSR, API routes, middleware and server actions are errors in a native build. Move per-request work into host code.
- Routing. Use
<Link>for navigation. A plain<a href>is a full page load. Dynamic routes are prerendered as a shell that matches at run time. - Startup and size. Cold start to a visible window is about 0.2 s and a release executable about 16 MB (10.9 MB stripped) on the Linux test machine; memory is mostly the system webview. These are order-of-magnitude figures; see Getting started.
- Window lifetime. The app quits when the last window closes, unless
native.window.keepAliveis set. The tray exists as long as it is set. - Platform status. Linux (WebKitGTK) is the most tested platform. The macOS and Windows implementations compile and have GUI tests in the CI native job; check the compatibility matrix for what each feature has been tested with.
- No Electron-only modules.
ipcMain,BrowserWindow,contextBridge,nativeImage,protocol,Menuand the rest do not exist at all. Search your code forrequire('electron')andfrom 'electron': every hit is a row in the tables above or a "none".
#Migration checklist
- Run
krate native initand move your UI intosrc/pages. - List every
ipcMain.handle/ipcMain.onchannel and write a host function for each; delete the preload script. - Replace each
webContents.sendwith a host signal, stream or view message. - Move startup code (menu, tray, shortcuts) to the first page or to Go host code.
- Replace Node
fs,path,osin the main process with@krate/app/fs, the directory functions, or Go. - Move settings to
kvordb. - Run
krate native check, setnative.permissions, fix anyKR72xxfinding. - Port the Playwright tests to
krate native test. - Set up
krate native package, signing and the update feed. - Test on all three operating systems.
Last updated: 2026-11-17
Contributors: Noinkin