Desktop apps with Electron
Docs Desktop Electron · 41 min to read this section

#Desktop apps with Electron

Kreft can package your app as a desktop application for Windows, macOS and Linux. The pages are the same .kreft files you already have; Electron only supplies the window.

#Quick start

BASH
kreft new my-app --electron   # a new app with desktop support
cd my-app && npm install
kreft electron:dev            # a desktop window only (the server is hidden), with hot reload
kreft electron:build          # an installer in dist-electron/

Add desktop support to an existing app instead:

BASH
kreft add electron            # config/electron.config.js, electron/, scripts, packages (runs npm install)

Everything you can change (window, menu, DevTools, security, tray, updates, installers) is in config/electron.config.js: see Desktop configuration.

#Commands

CommandWhat it does
kreft add electronWrites config/electron.config.js, the generated electron/main.js and electron/preload.js and the app icon build/icon.png, adds the scripts (including electron:build:mac, :win, :linux and :all) and the electron and electron-builder dev dependencies to package.json, and runs npm install. An existing config file is never replaced without a yes (--force replaces it). kreft electron:init (alias make:electron) does the same without npm install. It also removes the Google Fonts links from index.html, so the app starts without a network.
kreft electron:configChecks config/electron.config.js and prints the final settings (--json for machines).
kreft electron:devChecks the settings, then opens the app in a desktop window only: no browser opens and no URL is printed. The dev server runs hidden on a private port of your computer that only the window uses (hot reload works). Closing the window stops the server. Flags after the command go to the dev server.
kreft electron:buildRuns kreft build --base ./, then electron-builder. With no flag it builds for the system you are on.
kreft electron:build --mac.dmg and .zip for macOS.
kreft electron:build --winNSIS installer and portable .exe for Windows.
kreft electron:build --linuxAppImage, .deb and .rpm for Linux.
kreft electron:build --mac --win --linuxAll three systems in one run.
kreft electron:build --allThe same as --mac --win --linux.
npm run electron:build:mac, :win, :linux, :allShortcuts for the four commands above.

Other flags go straight to electron-builder: --x64, --arm64, --ia32, --armv7l, --universal (macOS) and --dir (an unpacked app folder only, no installer: fast for testing).

kreft electron is the same as kreft electron:dev. If the electron/ folder is missing, both commands create it first.

#Quick reference

I want to…Do this
Add desktop supportkreft new my-app --electron, or kreft add electron in an existing app
Open the app in its windowkreft electron (no browser, no URL)
Open DevToolskreft electron --devtools=bottom, devtools.openOnStart in the config file, or F12
Show, auto-hide or hide the menumenu.visibility ('hidden' is the default), kreft electron --menu=visible; kreftDesktop.setMenu('visible')
Change any settingEdit config/electron.config.js, or --set window.width=1000 for one run
Change the iconReplace build/icon.png (square PNG, 512×512 or bigger)
Change the app name and idapp.name and app.id in config/electron.config.js
Make an installernpm run electron:build:mac, :win, :linux or :all
Get help in the terminalkreft electron:help

#Project layout

TEXT
my-app/
├── config/
│   └── electron.config.js   your settings: the only file you edit
├── electron/
│   ├── main.js        generated: the main process, reads your settings (do not edit)
│   ├── preload.js     generated: the safe bridge exposed to your pages as window.kreftDesktop
│   ├── custom.js      yours, optional: your own main-process code (see "Your own code")
│   ├── kreft.resolved.json    written by the commands: your settings, checked and merged
│   └── builder.config.json    written by the commands: the electron-builder configuration
├── dist/              the static build the packaged app loads
├── dist-electron/     installers written by electron-builder
└── package.json       "main": "electron/main.js"

#How it runs

  • Development. The window loads http://localhost:8000 (change it with PORT). Hot reload, the DevTools button and the error overlay work as in the browser.
  • Packaged. The window loads dist/index.html from disk. That is a static build, so the Kreft backend (routes/, the database, kreft serve) is not inside the app. Point the API client at a server you host:
JS
const api = Kreftjs.api.create({ base: 'https://api.example.com' })

Use a PUBLIC_ value from .env for the address, so development and production can differ. Remember that CORS on your server must allow the app.

#Detecting the desktop app

JS
if (Kreftjs.isElectron) {
  const info = await Kreftjs.desktop.getInfo()   // { name, version, platform, arch, isPackaged }
}

Kreftjs.desktop is null in a normal browser, so the same page works in both.

#The desktop bridge

window.kreftDesktop (also Kreftjs.desktop) is the only way your pages reach the system. Nothing else from Node.js or Electron is exposed.

FunctionResult
getInfo(){ name, version, platform, arch, isPackaged }
minimize(), maximize(), close()Control the window. maximize() toggles.
openDevTools(mode), closeDevTools(), toggleDevTools()DevTools; mode is right, bottom, left or detach.
showMessageBox(options)A native message dialog.
showOpenDialog(options)A native "open file" dialog.
showSaveDialog(options)A native "save file" dialog.

Every call returns a promise. The dialog functions pass on only a fixed list of options (for example title, filters, properties); anything else is dropped.

KREFTJS
state path = ''

async function pick() {
  const r = await Kreftjs.desktop.showOpenDialog({
    title: 'Choose a file',
    filters: [{ name: 'Images', extensions: ['png', 'jpg'] }],
    properties: ['openFile'],
  })
  if (!r.canceled) path = r.filePaths[0]
}

#Adding your own desktop function

electron/main.js and preload.js are generated, so your code goes in electron/custom.js:

  1. In electron/custom.js, register a handler whose name starts with app:: ipcMain.handle('app:ping', () => 'pong').
  2. Call it from a page: await kreftDesktop.invoke('app:ping').

Pages can reach only channels that start with app:, never the built-in ones. Expose one narrow function per task. Never pass a path or a command from a page straight to the file system or a shell without checking it in custom.js. See Your own code.

#DevTools

They are available while you work, closed when the window opens, and off in the installed app. All three are settings (devtools.development, devtools.openOnStart, devtools.production, devtools.mode). To open them at start for one run:

BASH
kreft electron:dev --devtools          # right side
kreft electron:dev --devtools=bottom   # bottom, left or detach
kreft electron:dev --no-devtools
ELECTRON_DEVTOOLS=bottom kreft electron:dev

F12 or Ctrl+Shift+I toggles them (Cmd+Option+I on macOS) where they are allowed. In production they are refused: the shortcuts do nothing and DevTools that open anyway are closed. See Desktop configuration.

#The window menu

The menu bar is hidden by default. Set menu.visibility in config/electron.config.js ('hidden', 'visible' or 'auto'), or for one run:

BASH
kreft electron --menu=visible        # the menu bar
kreft electron --menu=auto           # hidden, press Alt to show it (Windows and Linux)
ELECTRON_MENU=show kreft electron    # the older variable still works: show | auto | hide

Or change it while the app runs, from a page:

JS
window.kreftDesktop.setMenu('visible')   // 'visible' | 'auto' | 'hidden' ('show' and 'hide' also work)
window.kreftDesktop.getMenu()            // the current mode

Your own menu goes in menu.template (see Desktop configuration).

On macOS the menu lives in the top bar of the screen, so visible and auto look the same, and hidden keeps only an app menu (with Quit) and an Edit menu, because macOS always has a menu bar and copy and paste need Edit. For your own menu (File, Edit…), use menu.template; to send a click to the page, give the entry an id and listen with kreftDesktop.onMenu.

#The app icon

kreft add electron copies the Kreft logo to build/icon.png. Replace it with your own square PNG, 512×512 or bigger (or point packaging.icon at another file). The window uses it, and electron-builder makes the .icns (macOS) and .ico (Windows) files from it. The app name and id are app.name and app.id in config/electron.config.js.

#Packaging and installers

BASH
kreft electron:build --mac                 # .dmg and .zip
kreft electron:build --win                 # NSIS installer and portable .exe
kreft electron:build --linux               # AppImage, .deb and .rpm
kreft electron:build --mac --win --linux   # all three
kreft electron:build --all                 # the same as the line above

The package.json scripts do the same: npm run electron:build:mac, :win, :linux and :all.

electron:build checks your settings, writes electron/builder.config.json from them and runs electron-builder, which writes to dist-electron/ (packaging.electron.outputDir). Flags go to electron-builder, for example kreft electron:build --mac --arm64. The defaults are:

SystemTargets
Windowsnsis installer (choose the folder), portable
macOSdmg, zip
LinuxAppImage, deb, rpm

Change the targets in packaging.electron (mac, win, linux) and the app id and name in app; anything else electron-builder knows goes in advanced.builder. The build block of package.json is not used any more. Build for each system on that system: a macOS installer needs a Mac (on a Mac, the Linux AppImage and the Windows installers build, but .deb and .rpm fail: build those on Linux, or remove them from build.linux.target). Code signing and notarisation (macOS) or a signing certificate (Windows) are set up through electron-builder (electron.build/code-signing) and are needed before you give the app to other people; unsigned macOS apps show a Gatekeeper warning.

The packaged app loads the built dist/index.html and does not start a backend. A frontend-only app works as is; a full-stack app (login, database) does not work once installed.

#npm run build or electron:build?

Adding Electron does not change npm run build. The two commands make different things:

CommandWhat it makesUse it for
npm run buildThe website in dist/, with paths that start at / (the docs/ folder is included).Putting the app on a web server.
npm run electron:buildThe same site built with --base ./ so it opens from a file, then an installer in dist-electron/.Giving the app to people as a desktop program.

A dist/ made by npm run build shows a white window if you open it in Electron, because its paths start at /. Run electron:build (or kreft build --base ./) first. Doing both is fine: electron:build rewrites dist/, so run npm run build again before you deploy the website.

#Security

The window follows Electron's security guidance, and each of these is a setting in security (the defaults are the safe values; turning one off prints a note):

  • contextIsolation, sandbox and webSecurity are on; nodeIntegration and allowRunningInsecureContent are off.
  • Links to other sites open in the system browser, and new windows are denied.
  • Navigation away from the app is blocked: only the dev server (development) or files inside dist/ (packaged) can load.
  • The bridge exposes named functions only, with the option lists described above.

Do not turn these off to make something work. Add a function in electron/custom.js instead. The permission requests of a page (location, camera, clipboard…) are all refused unless listed in security.permissions.

#Troubleshooting

ProblemFix
Electron is not installed locallykreft add -D electron
electron-builder is not installedkreft add -D electron-builder
A white window in the packaged appRun electron:build again; the build must use --base ./. Check that dist/index.html exists.
API calls fail in the packaged appThe backend is not bundled. Set an absolute base for the API client (see above).
The window opens before the server is readyIt waits up to 15 seconds. Check the terminal for a dev server error.
Port 8000 is takenNothing to do: the hidden server picks the next free port.

#Desktop apps with Tauri

Tauri is the other way to make a desktop app from your Kreft project. Your pages are the same .kreft files. Instead of shipping a browser like Electron, Tauri uses the web view the system already has (WebView2 on Windows, WebKit on macOS and Linux), so installers are small and the app uses less memory. The trade-off is that the small native part is written in Rust.

#What you need

You needWhy
Rust (cargo)Tauri compiles a small Rust program around your pages. Open a new terminal after installing.
Linux onlywebkit2gtk and a few libraries. See tauri.app/start/prerequisites.
Windows onlyThe Visual Studio C++ build tools. WebView2 is already part of Windows 10 and 11.

Install Rust once: from rustup.rs, or on a Mac with Homebrew:

BASH
brew install rustup
rustup default stable

Check it with cargo --version. Homebrew's rustup is keg-only (not linked into your normal path), so add it to your shell profile and open a new terminal:

BASH
echo 'export PATH=/opt/homebrew/opt/rustup/bin:$PATH' >> ~/.zshrc

Rust from rustup.rs puts cargo in ~/.cargo/bin, which its installer adds to your path. kreft tauri also looks in ~/.cargo/bin and in the Homebrew folder by itself, so it works even in a terminal that was opened before you installed Rust.

#Start

BASH
kreft new my-app --tauri      # a new project with Tauri included
cd my-app
npm install                   # installs @tauri-apps/cli
kreft tauri                   # opens the app in a desktop window

For a project you already have, run kreft add tauri (it also runs npm install). kreft tauri:init (alias kreft make:tauri) does the same without installing. It writes config/tauri.config.js, adds a src-tauri/ folder and three scripts to package.json, and never replaces your config file without a yes. Everything you can change (window, menu, DevTools, security, tray, updates, installers) is in config/tauri.config.js: see Desktop configuration.

CommandWhat it does
kreft tauri (or tauri:dev)Starts the dev server on a free port and opens a Tauri window on it. No browser tab opens. Close the window to stop both. --port N chooses the port.
kreft tauri:buildRuns kreft build --base ./, then tauri build. Installers are written to src-tauri/target/release/bundle/.
kreft tauri:initAdds Tauri to an existing project (kreft add tauri also installs the packages).
kreft tauri:configChecks config/tauri.config.js and prints the final settings (--json for machines).
kreft tauri:syncWrites src-tauri/ from the settings. tauri:dev and tauri:build do it by themselves.
kreft tauri:helpPrerequisites, files and options.

tauri:build builds for the system you run it on. Options: --debug (faster, larger build), --bundles dmg|app|nsis|msi|deb|rpm|appimage (which installers to make), --target <rust-triple> (another CPU). The first build compiles Rust and takes several minutes; later builds are quick.

#The files

FileWhat it is
config/tauri.config.jsYour settings. The only file you edit.
src-tauri/tauri.conf.jsonGenerated from your settings: name, identifier, window, security, installers. Options this file lacks go in advanced.tauriConf.
src-tauri/capabilities/default.jsonGenerated: what the window may do (core:default, plus notifications and updates when on, plus security.capabilities).
src-tauri/src/kreft_generated.rsGenerated: menu, DevTools, right-click menu, tray, notifications and updates. Never edit it.
src-tauri/src/main.rsYours. Written once; it calls kreft_generated::apply. Add your own commands here.
src-tauri/Cargo.tomlRust dependencies. Kreft rewrites only the lines between its two kreft-generated comments; add your own crates anywhere else.
build/icon.pngThe app icon: a square PNG, 1024x1024 is best. Kreft writes a default one if you have none. kreft tauri makes every size from it into src-tauri/icons/ with tauri icon whenever one is missing. To use your own, replace the file and run npx tauri icon build/icon.png.

#In the page

window.__TAURI__ exists only inside the Tauri window, so you can tell it from a browser:

JS
if (window.__TAURI__) {
  const name = await window.__TAURI__.core.invoke('greet', { name: 'Ada' })
}

invoke calls a Rust command that you write in main.rs and register with .invoke_handler(tauri::generate_handler![greet]).

#Electron or Tauri?

ElectronTauri
Installer sizeAbout 100 MBA few MB
NeedsNode.js onlyNode.js and Rust
Web viewIts own Chromium, the same everywhereThe system's, so small differences between systems
Your own system codeJavaScript (window.kreftDesktop bridge)Rust commands

window.kreftDesktop and the other Electron-only helpers do not exist in a Tauri window.

#The app icon

Tauri needs the icon in several sizes (src-tauri/icons/32x32.png, 128x128.png, 128x128@2x.png, icon.icns, icon.ico) and will not compile without them. You do not have to make them: kreft tauri and kreft tauri:build make every size from build/icon.png whenever one is missing, and write a default build/icon.png first if your project has none.

To use your own icon, put a square PNG (1024x1024 is best) at build/icon.png, then make the sizes again. Run it inside your project folder, where node_modules is:

BASH
cd my-app
npx tauri icon build/icon.png

tauri icon also writes iOS and Android icon folders next to the desktop ones. A Tauri desktop app does not use them, so you can ignore them.

#What has been tested

tauri:init, kreft new --tauri, tauri:dev (the window opens on a free port and closes together with the dev server) and tauri:build --debug --bundles app (a macOS .app) were run with Rust 1.99 on macOS. Release installers, Windows and Linux were not tested.

#Tauri troubleshooting

ProblemFix
Rust is not installed (cargo was not found)Install Rust (see the install steps above). If it is installed already, your terminal cannot see it: run cargo --version; if that says "command not found", add its folder to your path: export PATH="$HOME/.cargo/bin:$PATH" for rustup.rs, or export PATH=/opt/homebrew/opt/rustup/bin:$PATH for Homebrew (put the line in ~/.zshrc, then open a new terminal). kreft tauri already looks in both folders, so this error usually means Rust is not installed at all.
failed to open icon …/icons/32x32.png (a Rust "proc macro panicked" error)The icon sizes were not made. In your project folder run npx tauri icon build/icon.png (any square PNG works; if you have none, copy one to build/icon.png first). Kreft versions after 0.0.28-beta do this by themselves.
npx tauri says could not determine executable to runYou are not in your project folder, or @tauri-apps/cli is not installed. cd into the project and run npm install.
The Tauri command line is not installedRun npm install (or kreft add -D @tauri-apps/cli).
A white window in the packaged appRun tauri:build again; the build must use --base ./. Check that dist/index.html exists.
API calls fail in the packaged appThe backend is not bundled. Set an absolute base for the API client, as for Electron.
Linux build fails on webkit2gtkInstall the Linux libraries listed above.
Port 8000 is takenNothing to do: the dev server picks the next free port.

#Desktop configuration

Electron and Tauri apps are set up from one readable JavaScript file each: config/electron.config.js and config/tauri.config.js. You change the window, the menu, DevTools, security, the tray, notifications, updates and the installers there. You never edit the native files Kreft generates (electron/main.js, src-tauri/tauri.conf.json, src-tauri/src/kreft_generated.rs): they read your settings.

#Add a runtime

BASH
kreft add electron            # config/electron.config.js, electron/, scripts, packages (runs npm install)
kreft add tauri               # config/tauri.config.js, src-tauri/, scripts, packages
kreft add electron tauri      # both, side by side
FlagWhat it does
--no-installDo not run npm install.
--forceReplace an existing config file with the defaults (the old one is saved as .bak).

An existing config file is never replaced without a yes. On a terminal kreft add asks Replace it with the default settings? [y/N]. Without a terminal (CI) it keeps your file and tells you to use --force. kreft new my-app --electron and --tauri write the same files. kreft electron:init and kreft tauri:init do the same as add, without installing packages.

#The config file

The file lists every option with its default, so you can see what exists. Change a value, save, run kreft electron:dev (or tauri:dev) again. Options you delete keep their default.

JS
// config/electron.config.js (a CommonJS project)
/** @type {import('kreftjs/desktop').ElectronConfig} */
module.exports = {
  window: { width: 1000, height: 700 },
  menu: { visibility: 'hidden' },
  devtools: { openOnStart: false },
}

In a project with "type": "module" in package.json the file uses export default { … } instead; kreft add writes the right form. A .cjs or .mjs file name also works. The file may export a function that returns the settings (it may be async), which receives the mode ('development' or 'production'), the platform and the environment:

JS
// example: electron
module.exports = ({ mode }) => ({
  window: { title: mode === 'development' ? 'My app (dev)' : 'My app' },
  devtools: { openOnStart: mode === 'development' },
})

#What is used, in this order

The last one wins. Each layer is checked on its own, then they are merged group by group (a list is replaced, not added to).

#LayerWhereApplies to
1Built-in defaultsthe tables belowthe runtime
2Shared KreftJS configurationkreftjs.config.json → "desktop"both runtimes
3Shared environmentKREFT_DESKTOP_WINDOW_WIDTH=1000both runtimes
4Runtime configuration fileconfig/electron.config.js, config/tauri.config.jsone runtime
5Runtime environmentKREFT_ELECTRON_WINDOW_WIDTH=1000, KREFT_TAURI_WINDOW_WIDTH=1000 (and the older ELECTRON_MENU, ELECTRON_DEVTOOLS)one runtime
6Command line--set window.width=1000, --menu=visible, --devtools[=mode], --no-devtoolsone run

Layers 2 and 3 serve both runtimes, so an option or value one runtime does not have (security.sandbox in Tauri, menu.visibility: 'auto' in Tauri) is ignored there with a note, not an error. In layers 4 to 6 the same mistake is an error, because you wrote it for that runtime.

JSON
{ "desktop": { "window": { "width": 1100, "height": 760 }, "tray": { "enabled": true } } }

The environment variable name of an option is its path in capitals with _ between words: window.minWidth → KREFT_ELECTRON_WINDOW_MIN_WIDTH. A list is written with commas (KREFT_ELECTRON_SECURITY_PERMISSIONS=geolocation,media) or as JSON. --set takes any option (--set devtools.mode=bottom --set window.resizable=false); a value is read as JSON when it can be (true, 1000, null), as text otherwise.

#Check your settings

BASH
kreft electron:config       # checks config/electron.config.js and prints the final settings
kreft tauri:config --json   # the same for Tauri, as JSON

dev and build check the settings too, before they start anything, so a mistake stops a build before it spends minutes. Every option is validated: unknown names, wrong types, numbers out of range, values the runtime does not support. All the problems are listed together, with where they come from:

TEXT
The tauri configuration has 3 problems:
  - menu.visibility: "auto" is not allowed in tauri (that value is for Electron). Use one of: hidden, visible.
    (from config/tauri.config.js)
  - window.widht: unknown option. Did you mean "width"? The options in window are: title, width, height, …
    (from config/tauri.config.js)
  - window.minWidth: is 1300, larger than window.width (1200). Lower minWidth or raise width.

Settings that are allowed but unsafe (security.nodeIntegration: true, devtools.production: true…) are not errors; each one prints a note.

#The defaults

SettingDefaultMeaning
menu.visibility'hidden'No menu bar. On macOS the system menu bar always exists, so a minimal app menu (Quit) and an Edit menu stay: without Edit, Cmd+C and Cmd+V stop working.
devtools.developmenttrueDevTools are available while you work (F12 or Ctrl+Shift+I; Cmd+Option+I on macOS).
devtools.openOnStartfalse…but closed when the window opens. Set it to true to open them by themselves.
devtools.productionfalseNo DevTools in the installed app: the shortcuts do nothing, and in Electron DevTools that open anyway are closed. In Tauri a release build is made without its devtools feature.
Electron securitycontextIsolation: true, sandbox: true, nodeIntegration: false, webSecurity: truePages cannot reach Node.js. Turning one off prints a note.
security.blockNewWindowstrueA page cannot open windows; a link to another site opens in the system browser.
webview.allowedNavigation[]The window cannot go to any site except the app itself.
notifications.enabledfalseA page may not show notifications until you allow it.
window1200 × 800, minimum 800 × 600Resizable, centered. In both runtimes the size is the page area, without the title bar.

#Every option

Runtime says where the option exists. Setting an Electron-only option in config/tauri.config.js (or the other way round) is an error that tells you what to use instead.

<!-- desktop-options:start (made by "node bin/desktop/docs.js --write": do not edit between the markers) -->

#app

Name, id and version of the app.

OptionRuntimeDefaultWhat it does
app.namebothnullThe name people see. Default: the "productName" or "name" in package.json.
app.idbothnullThe reverse-domain id, for example "com.acme.notes". Default: com.kreftjs. followed by the lowercase name.
app.versionbothnullThe version number. Default: the "version" in package.json.
app.descriptionbothnullA one-line description. Default: the "description" in package.json.
app.authorbothnullWho makes the app. Default: the "author" in package.json.
app.homepagebothnullThe web address of the app. Default: the "homepage" in package.json.
app.copyrightbothnullThe copyright line shown in the installer and the About box.

#window

How the main window looks and behaves.

OptionRuntimeDefaultWhat it does
window.titlebothnullThe window title. Default: the app name.
window.widthboth1200Width in pixels. From 200 to 16000.
window.heightboth800Height in pixels. From 150 to 16000.
window.minWidthboth800The window cannot be made narrower than this. From 0 to 16000.
window.minHeightboth600The window cannot be made lower than this. From 0 to 16000.
window.maxWidthbothnullThe window cannot be made wider than this. null: no limit. From 200 to 32000.
window.maxHeightbothnullThe window cannot be made higher than this. null: no limit. From 150 to 32000.
window.xbothnullDistance from the left edge of the screen. null: the system chooses (or the window is centered). From -32000 to 32000.
window.ybothnullDistance from the top edge of the screen. null: the system chooses (or the window is centered). From -32000 to 32000.
window.centerbothtrueOpen the window in the middle of the screen (ignored when x and y are set).
window.resizablebothtrueLet people resize the window.
window.fullscreenbothfalseOpen the window in full screen.
window.maximizedbothfalseOpen the window maximized.
window.alwaysOnTopbothfalseKeep the window above all others.
window.framebothtrueDraw the system title bar and border. false: a window without them.
window.transparentbothfalseA see-through window background (the page must draw its own background).
window.backgroundColorboth'#ffffff'The colour shown before the page has drawn, as #rrggbb.
window.themeboth'system'The look of the window frame and the system dialogs. Values: system, light, dark.
window.skipTaskbarbothfalseKeep the window out of the taskbar or dock.
window.showOnReadyElectrontrueShow the window only when the page is ready, so it never opens as a white flash.

The native application menu.

OptionRuntimeDefaultWhat it does
menu.visibilityboth'hidden'"hidden": no menu bar. "visible": the menu bar. "auto": hidden until Alt is pressed (Electron on Windows and Linux only). On macOS the system menu bar always exists, so "hidden" keeps a minimal app and Edit menu: without them, copy and paste shortcuts stop working. Values: Electron hidden, visible, auto; Tauri hidden, visible.
menu.templatebothnullYour own menu, as a list of top-level entries with a submenu. null: the default menu of the runtime.

#contextMenu

The right-click menu.

OptionRuntimeDefaultWhat it does
contextMenu.enabledbothtrueAllow the right-click menu. false: right-click does nothing.
contextMenu.itemsElectron['copy', 'cut', 'paste', 'selectAll']The entries of the right-click menu on text.
contextMenu.inspectElementElectrontrueAdd "Inspect element" when DevTools are allowed.

#devtools

The developer tools.

OptionRuntimeDefaultWhat it does
devtools.developmentbothtrueAllow DevTools while you work (kreft electron:dev, kreft tauri:dev).
devtools.productionbothfalseAllow DevTools in the installed app. Keep it false unless you need to debug a release.
devtools.openOnStartbothfalseOpen DevTools by themselves when the window opens (only where they are allowed).
devtools.modebothElectron 'right', Tauri 'detach'Where DevTools open. Tauri can only open them in their own window. Values: Electron right, bottom, left, detach; Tauri detach.
devtools.shortcutbothtrueF12 and Ctrl+Shift+I (Cmd+Option+I on macOS) toggle DevTools where they are allowed.

#webview

The web page inside the window.

OptionRuntimeDefaultWhat it does
webview.zoomFactorboth1The page zoom. 1 is 100 %. From 0.25 to 5.
webview.userAgentbothnullText sent to servers as the browser name. null: the default of the runtime.
webview.spellcheckElectronfalseUnderline misspelled words in text fields.
webview.backgroundThrottlingElectrontrueSlow the page down when the window is hidden.
webview.openExternalLinksInBrowserbothtrueA link to another site opens in the system browser, not in the app window.
webview.allowedNavigationboth[]Origins (like "https://login.acme.com") the window may go to besides the app itself. Everything else is blocked.

#security

What the page may do. The defaults are the safe ones.

OptionRuntimeDefaultWhat it does
security.cspbothnullThe Content-Security-Policy of the pages, for example "default-src 'self'". null: none is added.
security.blockNewWindowsbothtruePages cannot open new windows.
security.contextIsolationElectrontrueKeep the page and the preload script in separate JavaScript worlds.
security.sandboxElectrontrueRun the page in the operating system sandbox.
security.nodeIntegrationElectronfalseGive the page access to Node.js. Leave it false: any script on the page could then run programs on the computer.
security.webSecurityElectrontrueKeep the same-origin policy of the browser.
security.allowRunningInsecureContentElectronfalseLet an https page load http scripts.
security.permissionsElectron[]Browser permissions the page may get, for example "geolocation", "media", "clipboard-read". Notifications are allowed by notifications.enabled.
security.capabilitiesTauri[]Extra Tauri permissions for the window, like "dialog:default" (the plugin must also be added in src-tauri/Cargo.toml). "core:default" is always there.
security.globalTauriTauritruePut the Tauri API on window.__TAURI__.

#tray

The system tray icon.

OptionRuntimeDefaultWhat it does
tray.enabledbothfalseShow an icon in the system tray (the menu bar on macOS).
tray.iconbothnullA PNG file, relative to the project. null: the app icon.
tray.tooltipbothnullText shown when the mouse rests on the icon. null: the app name.
tray.closeToTraybothfalseClosing the window hides it; the app keeps running in the tray. Choose "Quit" in the tray menu to leave.
tray.clickActionboth'toggle'What a click on the tray icon does. Values: toggle, show, none.
tray.menuboth[{'label':'Show', 'action':'show'}, {'type':'separator'}, {'label':'Quit', 'action':'quit'}]The entries of the tray menu.

#notifications

System notifications.

OptionRuntimeDefaultWhat it does
notifications.enabledbothfalseThe page may show system notifications. In Tauri this adds the notification plugin (a crate and a permission).

#updates

Updates.

OptionRuntimeDefaultWhat it does
updates.enabledbothfalseLook for new versions of the app.
updates.urlbothnullThe https address of the folder that holds the update files (Electron: latest.yml and the installers; Tauri: the update JSON).
updates.channelboth'latest'The release channel, like "latest" or "beta".
updates.checkOnStartbothtrueLook for an update each time the app starts (installed app only).
updates.autoDownloadElectronfalseDownload an update without asking.
updates.pubkeyTaurinullThe public key that update files are signed with (made by "npx tauri signer generate").

#packaging

How the installers are made.

OptionRuntimeDefaultWhat it does
packaging.iconboth'build/icon.png'The app icon, a square PNG (1024×1024 is best), relative to the project.
packaging.categorybothnullThe category in app stores and menus, like "public.app-category.productivity" (macOS) or "Utility" (Linux). null: the default of the runtime.
packaging.electron.outputDirboth'dist-electron'The folder the installers are written to.
packaging.electron.macboth['dmg', 'zip']Installers to make for macOS.
packaging.electron.winboth['nsis', 'portable']Installers to make for Windows.
packaging.electron.linuxboth['AppImage', 'deb', 'rpm']Installers to make for Linux.
packaging.electron.asarbothtruePack the app files into one archive.
packaging.electron.compressionboth'normal'How much the installer is compressed. Values: store, normal, maximum.
packaging.electron.filesboth['dist/**/*', 'electron/**/*', 'package.json']The files that go into the app (build/icon.png and the tray icon are added).
packaging.electron.extraResourcesboth[]Extra files copied next to the app, relative to the project.
packaging.tauri.targetsbothnullInstallers to make. null: all that fit the system you build on.
packaging.tauri.resourcesboth[]Extra files that go into the app, relative to src-tauri/.
packaging.tauri.macMinimumSystemVersionboth'10.15'The oldest macOS the app runs on.
packaging.tauri.windowsWebviewInstallboth'downloadBootstrapper'How the installer gets WebView2 on Windows. Values: skip, downloadBootstrapper, embedBootstrapper, offlineInstaller.

#advanced

A way out for options this file does not know. Values here are merged into the generated native configuration last.

OptionRuntimeDefaultWhat it does
advanced.builderElectron{ … }Merged into the electron-builder configuration. Use it for options this file does not have.
advanced.tauriConfTauri{ … }Merged into src-tauri/tauri.conf.json. Use it for options this file does not have.

<!-- desktop-options:end -->

#Electron and Tauri are not the same

The two runtimes do not offer the same things, so each has its own adapter (bin/desktop/electron-adapter.js, bin/desktop/tauri-adapter.js) and the options that exist in only one are marked above. The differences that matter:

ElectronTauri
What the settings becomeelectron/kreft.resolved.json (read by electron/main.js) and electron/builder.config.json (for electron-builder)src-tauri/tauri.conf.json, src-tauri/capabilities/default.json, the dependency block of Cargo.toml and src-tauri/src/kreft_generated.rs
Menu 'auto' (Alt shows it)Yes (Windows, Linux)No
Custom menu rolesthe shared ones, and reload, forceReload, toggleDevTools, zoomIn, zoomOut, resetZoomthe shared ones only (undo, redo, cut, copy, paste, selectAll, minimize, close, quit, fullscreen, about)
Right-click menuYou choose the entries (contextMenu.items)The web view's own menu; only on or off (contextMenu.enabled)
DevToolsright, bottom, left or detached; can be switched off in developmentdetached window only; a development build always has them (devtools.development must be true)
Permissionssecurity.permissions (browser permissions)security.capabilities (Tauri permissions); notifications and updates add theirs by themselves
Notificationsa permission, and kreftDesktop.notify(title, body)the tauri-plugin-notification crate, added by notifications.enabled (use its JavaScript API in the page)
Updateselectron-updater (install it: kreft add electron-updater) and a generic feed at updates.urltauri-plugin-updater, a signed update JSON at updates.url and the public key in updates.pubkey
Installerspackaging.electron (targets per system, asar, compression…)packaging.tauri (targets, resources, WebView2 install mode…)
A way outadvanced.builder (merged into the electron-builder configuration)advanced.tauriConf (merged into tauri.conf.json)
Page APIwindow.kreftDesktopwindow.__TAURI__ (security.globalTauri)
Events to the pagekreftDesktop.onMenu(cb), onTray(cb), onUpdate(cb)window.__TAURI__.event.listen('kreft:menu', cb), 'kreft:tray', 'kreft:update-available'

#Examples

A custom menu, a tray icon that keeps the app running, and a notification (Electron):

JS
// example: electron
module.exports = {
  menu: {
    visibility: 'visible',
    template: [
      { label: 'File', submenu: [{ label: 'New note', id: 'note-new', accelerator: 'CmdOrCtrl+N' }, { type: 'separator' }, { role: 'quit' }] },
      { label: 'Edit', submenu: [{ role: 'undo' }, { role: 'redo' }, { type: 'separator' }, { role: 'copy' }, { role: 'paste' }] },
    ],
  },
  tray: {
    enabled: true,
    closeToTray: true,
    tooltip: 'My notes',
    menu: [{ label: 'Open', action: 'show' }, { label: 'New note', action: 'emit', id: 'note-new' }, { type: 'separator' }, { label: 'Quit', action: 'quit' }],
  },
  notifications: { enabled: true },
}

In the page, listen for the entries that have an id:

JS
if (window.kreftDesktop) {
  kreftDesktop.onMenu((id) => { if (id === 'note-new') newNote() })
  kreftDesktop.onTray((id) => { if (id === 'note-new') newNote() })
  kreftDesktop.notify('Saved', 'Your note was saved.')
}

A fixed-size window, no right-click menu, and a strict content policy (Tauri):

JS
// example: tauri
module.exports = {
  window: { width: 480, height: 640, minWidth: 480, minHeight: 640, resizable: false, center: true },
  contextMenu: { enabled: false },
  security: { csp: "default-src 'self'; connect-src 'self' https://api.acme.test" },
  webview: { allowedNavigation: ['https://login.acme.test'] },
}

Updates (Tauri). Make the key pair once with npx tauri signer generate -w ~/.tauri/notes.key, keep the private key secret, and put the public key in the file:

JS
// example: tauri
module.exports = {
  updates: {
    enabled: true,
    url: 'https://updates.acme.test/notes/{{target}}/{{current_version}}',
    pubkey: 'dW50cnVzdGVkIGNvbW1lbnQ6IG1pbmlzaWduIHB1YmxpYyBrZXk6IEFCQ0RFRjAxMjM0NTY3ODk=',
  },
  notifications: { enabled: true },
  security: { capabilities: ['dialog:default'] },
}

Updates and installers (Electron), with an option this file does not have, passed on to electron-builder:

JS
// example: electron
module.exports = {
  app: { id: 'com.acme.notes', name: 'Acme Notes', copyright: 'Copyright © 2026 Acme' },
  updates: { enabled: true, url: 'https://updates.acme.test/notes', channel: 'latest' },
  packaging: {
    category: 'public.app-category.productivity',
    electron: { mac: ['dmg'], win: ['nsis'], linux: ['AppImage', 'deb'], compression: 'maximum' },
  },
  advanced: { builder: { mac: { hardenedRuntime: true } } },
}

#Both runtimes in one project

kreft add electron tauri installs both. They are independent: each has its own file (config/electron.config.js, config/tauri.config.js), folder (electron/, src-tauri/) and commands (electron:dev, tauri:dev…), and one never reads the other's file. Settings you want in both go in kreftjs.config.json under "desktop". The page can tell which one it runs in (window.kreftDesktop or window.__TAURI__).

#Your own code

You never edit the generated files, so your own code has its own place:

  • Electron. Create electron/custom.js: it is loaded after the window opens. Register handlers there and call them from a page through the app: channels (a page can reach no other channel):
    // electron/custom.js
    const { ipcMain } = require('electron')
    module.exports = function (app, win, config) {
      ipcMain.handle('app:ping', () => 'pong')
    }
    const answer = await kreftDesktop.invoke('app:ping')      // 'pong'
    kreftDesktop.on('app:progress', (n) => update(n))          // sent with win.webContents.send('app:progress', n)
  • Tauri. Write your commands in src-tauri/src/main.rs, which is yours and is never overwritten; it already calls kreft_generated::apply. Calling .setup(…) or .invoke_handler(…) on the builder replaces what was set before, so call kreft_generated::setup(app)? inside your own setup.

#TypeScript and editor autocomplete

kreftjs/desktop has the types, made from the same description as the validation, with a comment on every option:

JS
/** @type {import('kreftjs/desktop').TauriConfig} */
module.exports = { devtools: { mode: 'detach' } }
JS
const { defineElectronConfig } = require('kreftjs/desktop')
module.exports = defineElectronConfig({ window: { width: 1000 } })

The editor then completes option names and values, and underlines a value the runtime does not accept (for example menu.visibility: 'auto' in a Tauri file). ElectronConfig, TauriConfig and SharedDesktopConfig (for kreftjs.config.json) are exported. In a TypeScript project, name the file config/electron.config.cjs or use export default.

#If you used Electron or Tauri with an earlier Kreft

  • The menu is hidden by default now. It used to be visible. Set menu.visibility: 'visible' (or ELECTRON_MENU=show) to bring it back.
  • ELECTRON_MENU and ELECTRON_DEVTOOLS still work, as layer 5.
  • The build block of package.json is ignored. Installers are made from packaging and app in config/electron.config.js. Move your appId, productName and targets there (or into advanced.builder).
  • electron/main.js and preload.js are generated. A hand-written main.js is saved as main.js.bak and replaced the next time you run a command; move your code to electron/custom.js.
  • src-tauri/tauri.conf.json, capabilities/default.json and src/kreft_generated.rs are written from the config file every time. Put options this file lacks in advanced.tauriConf. Your Cargo.toml keeps your own dependencies; Kreft only writes the lines between its two kreft-generated comments.
  • window.width and height are the page area in Electron too (they used to include the title bar).

#What has been tested

Automated tests (npm test) cover the defaults of both runtimes, the six layers and their order, validation (unknown, wrong, unsupported and out-of-range values, with the messages), CommonJS and ESM projects, never overwriting a config file, both runtimes in one project, the files made for electron-builder and Tauri, and the TypeScript definitions and the examples above.

The runtime tests (npm run test:desktop) start the real apps and read back what they do: the menu is hidden, DevTools are closed at start, open with the shortcut in development and are refused in production, openOnStart works only where DevTools are allowed, the window settings and the secure webPreferences are in effect, the file < environment < command line order holds in the real window, a production Electron build is packaged, starts and holds the checked configuration, and Tauri development and release builds compile with the safe defaults and with everything turned on. They were run on macOS (Apple silicon). Windows and Linux are not tested by Kreft: the same code runs there, but check your own build on each system.

#Configuration troubleshooting

ProblemFix
unknown optionA name is misspelled or in the wrong group. The message lists the valid names and suggests the closest.
is not supported by Tauri / by ElectronThe option belongs to the other runtime. The message says what to use instead (see the table above).
x and y go togetherSet both window.x and window.y, or neither.
config/electron.config.js could not be loadedA syntax error, or the wrong module style: module.exports in a "type": "module" project (use export default or .cjs).
My change has no effectRestart kreft electron:dev / tauri:dev: the file is read at start. In Tauri, check kreft tauri:config shows your value.
electron/kreft.resolved.json is missingStart the app with kreft electron:dev or kreft electron:build; they write it. Running electron . by hand does not.
A Tauri main.rs that ignores the settingsThe note says to add mod kreft_generated; and kreft_generated::apply(tauri::Builder::default()).
updates.pubkey is requiredTauri verifies every update. npx tauri signer generate -w ~/.tauri/app.key, then put the public key in the file.
Shortcuts (F12) do nothingDevTools are off in production (devtools.production), or devtools.shortcut is false.

#One codebase. Every screen.

One codebase, every screen. A single Kreft project runs as a web application, a desktop app for macOS, Linux and Windows (with Electron or Tauri), and a phone or tablet app for iOS, Android and HarmonyOS. TV apps are coming soon and are not available yet. The pages are the same .kreft files everywhere; each target only adds a native shell around them.

#Where a Kreft app runs

TargetShellAdd itRun itPackage itStatus
Web applicationthe browserkreft new my-appkreft devkreft buildTested
macOS (Electron)Electronkreft add electronkreft electron:devkreft electron:build --macTested
Linux (Electron)Electronkreft add electronkreft electron:devkreft electron:build --linuxNot tested here
Windows (Electron)Electronkreft add electronkreft electron:devkreft electron:build --winNot tested here
macOS (Tauri)Taurikreft add taurikreft tauri:devkreft tauri:buildTested
Linux (Tauri)Taurikreft add taurikreft tauri:devkreft tauri:buildNot tested here
Windows (Tauri)Taurikreft add taurikreft tauri:devkreft tauri:buildNot tested here
iOSCapacitorkreft new my-app --mobilekreft mobile:run --ioskreft mobile:release --iosNot tested here
AndroidCapacitorkreft new my-app --mobilekreft mobile:run --androidkreft mobile:release --androidTested
HarmonyOSArkTS web viewkreft new my-app --harmonykreft harmony:open (DevEco Studio)kreft mobile:release --harmonyNot tested here
Android TV, tvOS, webOS, TizenComing soon

What the status means. Tested means Kreft's own tests ran it for real: the Electron and Tauri apps were started on macOS and checked (menu, DevTools, window, security, production builds), and an Android app was run on the emulator and built as a signed release. Not tested here means the same code is meant to run on that system, but Kreft has not run it there: build it on that system and check it before you ship. Coming soon means planned and not available.

#Which one do I choose?

I want…Choose
A website onlyThe web. Nothing to add.
A desktop app, and I want the page to look the same on every systemElectron. It ships its own Chromium. Needs only Node.js. Installers are about 100 MB.
A desktop app with a small installer, and I can use RustTauri. It uses the system's web view. Installers are a few megabytes. Needs Rust.
An app in Google PlayAndroid.
An app in the App StoreiOS. Needs a Mac with Xcode and a paid Apple Developer account.
An app for Huawei phones and tabletsHarmonyOS. Needs DevEco Studio.

Both desktop runtimes can live in one project (kreft add electron tauri), and a project can have desktop and phone targets together (kreft new my-app --mobile --electron). They share your pages. See Desktop configuration for the settings file each one reads.

#What each target needs

TargetYou need installed
WebNode.js 22.5 or newer
ElectronNode.js (Electron and electron-builder come with kreft add electron)
TauriNode.js and Rust; on Linux the WebKitGTK libraries; on Windows the Visual Studio C++ build tools
AndroidAndroid Studio and a Java from 21 to 23
iOSA Mac with Xcode
HarmonyOSDevEco Studio (and a Huawei developer account to sign for a real device)

Build a desktop installer on the system it is for: a macOS installer needs a Mac, a Windows installer is best built on Windows, a Linux one on Linux.

#What is different on each target

  • The backend does not run inside an app. A desktop or phone app holds your built pages. Point the API client at a server you host (for phones, build with --api-url https://…). See Desktop apps with Electron and Mobile apps.
  • The address style. A packaged app loads its pages from files, so the router uses mode: 'hash' there; harmony:init sets that up so the website keeps its normal addresses.
  • The native bridge differs. Electron gives pages window.kreftDesktop; Tauri gives window.__TAURI__; the phone apps give Kreftjs.native (camera, files, share, haptics…). Write the page once and ask which one it is running in:
JS
if (Kreftjs.isElectron) {            // an Electron window
  kreftDesktop.notify('Saved', 'Your note was saved.')
} else if (Kreftjs.isTauri) {        // a Tauri window
  window.__TAURI__.event.emit('saved')
} else if (Kreftjs.native.isNative()) {  // an iOS or Android app
  Kreftjs.native.system.share({ text: 'Hello' })
}

Kreftjs.native.platform()    // 'ios' | 'android' | 'electron' | 'tauri' | 'web'
Kreftjs.native.isDesktop()   // true in Electron and Tauri

HarmonyOS apps run your pages in a web view, so they behave as the web there; use feature checks ('share' in navigator) for anything that depends on the device.

#TV apps (coming soon)

TV apps are planned and not available yet. Kreft has no TV packaging and no remote-control navigation today. What is planned:

TargetPlan
Android TVThe Android app, with a remote-control (D-pad) focus ring and a TV layout kit
Apple tvOSA tvOS shell around the same pages
LG webOSA packaged web app for LG TVs
Samsung TizenA packaged web app for Samsung TVs

There is no release date, and nothing here is promised until it ships and is tested. Until then, a TV that has a web browser can open your website; that is not a packaged TV app and has no focus handling for a remote.

#Platform commands at a glance

I want to…Command
Add Electron or Tauri to an appkreft add electron, kreft add tauri, or kreft add electron tauri
Check the desktop settingskreft electron:config, kreft tauri:config
Run a desktop appkreft electron:dev, kreft tauri:dev
Make desktop installerskreft electron:build [--mac] [--win] [--linux], kreft tauri:build
Add phone supportkreft new my-app --mobile, or kreft mobile:init
Run on a phone or emulatorkreft mobile:run --android, kreft mobile:run --ios, kreft mobile:dev
Add HarmonyOSkreft new my-app --harmony, or kreft harmony:init
Build and open HarmonyOSkreft harmony:build --api-url https://…, kreft harmony:open
Release a phone appkreft mobile:release --android, --ios, --harmony; the steps are in Publishing your app to Google Play and the App Store