#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
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:
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
| Command | What it does |
|---|---|
kreft add electron | Writes 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:config | Checks config/electron.config.js and prints the final settings (--json for machines). |
kreft electron:dev | Checks 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:build | Runs 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 --win | NSIS installer and portable .exe for Windows. |
kreft electron:build --linux | AppImage, .deb and .rpm for Linux. |
kreft electron:build --mac --win --linux | All three systems in one run. |
kreft electron:build --all | The same as --mac --win --linux. |
npm run electron:build:mac, :win, :linux, :all | Shortcuts 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 support | kreft new my-app --electron, or kreft add electron in an existing app |
| Open the app in its window | kreft electron (no browser, no URL) |
| Open DevTools | kreft electron --devtools=bottom, devtools.openOnStart in the config file, or F12 |
| Show, auto-hide or hide the menu | menu.visibility ('hidden' is the default), kreft electron --menu=visible; kreftDesktop.setMenu('visible') |
| Change any setting | Edit config/electron.config.js, or --set window.width=1000 for one run |
| Change the icon | Replace build/icon.png (square PNG, 512×512 or bigger) |
| Change the app name and id | app.name and app.id in config/electron.config.js |
| Make an installer | npm run electron:build:mac, :win, :linux or :all |
| Get help in the terminal | kreft electron:help |
#Project layout
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 withPORT). Hot reload, the DevTools button and the error overlay work as in the browser. - Packaged. The window loads
dist/index.htmlfrom 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:
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
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.
| Function | Result |
|---|---|
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.
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:
- In
electron/custom.js, register a handler whose name starts withapp::ipcMain.handle('app:ping', () => 'pong'). - 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:
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:devF12 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:
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 | hideOr change it while the app runs, from a page:
window.kreftDesktop.setMenu('visible') // 'visible' | 'auto' | 'hidden' ('show' and 'hide' also work)
window.kreftDesktop.getMenu() // the current modeYour 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
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 aboveThe 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:
| System | Targets |
|---|---|
| Windows | nsis installer (choose the folder), portable |
| macOS | dmg, zip |
| Linux | AppImage, 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:
| Command | What it makes | Use it for |
|---|---|---|
npm run build | The website in dist/, with paths that start at / (the docs/ folder is included). | Putting the app on a web server. |
npm run electron:build | The 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,sandboxandwebSecurityare on;nodeIntegrationandallowRunningInsecureContentare 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
| Problem | Fix |
|---|---|
Electron is not installed locally | kreft add -D electron |
electron-builder is not installed | kreft add -D electron-builder |
| A white window in the packaged app | Run electron:build again; the build must use --base ./. Check that dist/index.html exists. |
| API calls fail in the packaged app | The backend is not bundled. Set an absolute base for the API client (see above). |
| The window opens before the server is ready | It waits up to 15 seconds. Check the terminal for a dev server error. |
| Port 8000 is taken | Nothing 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 need | Why |
|---|---|
Rust (cargo) | Tauri compiles a small Rust program around your pages. Open a new terminal after installing. |
| Linux only | webkit2gtk and a few libraries. See tauri.app/start/prerequisites. |
| Windows only | The 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:
brew install rustup
rustup default stableCheck 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:
echo 'export PATH=/opt/homebrew/opt/rustup/bin:$PATH' >> ~/.zshrcRust 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
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 windowFor 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.
| Command | What 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:build | Runs kreft build --base ./, then tauri build. Installers are written to src-tauri/target/release/bundle/. |
kreft tauri:init | Adds Tauri to an existing project (kreft add tauri also installs the packages). |
kreft tauri:config | Checks config/tauri.config.js and prints the final settings (--json for machines). |
kreft tauri:sync | Writes src-tauri/ from the settings. tauri:dev and tauri:build do it by themselves. |
kreft tauri:help | Prerequisites, 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
| File | What it is |
|---|---|
config/tauri.config.js | Your settings. The only file you edit. |
src-tauri/tauri.conf.json | Generated from your settings: name, identifier, window, security, installers. Options this file lacks go in advanced.tauriConf. |
src-tauri/capabilities/default.json | Generated: what the window may do (core:default, plus notifications and updates when on, plus security.capabilities). |
src-tauri/src/kreft_generated.rs | Generated: menu, DevTools, right-click menu, tray, notifications and updates. Never edit it. |
src-tauri/src/main.rs | Yours. Written once; it calls kreft_generated::apply. Add your own commands here. |
src-tauri/Cargo.toml | Rust dependencies. Kreft rewrites only the lines between its two kreft-generated comments; add your own crates anywhere else. |
build/icon.png | The 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:
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?
| Electron | Tauri | |
|---|---|---|
| Installer size | About 100 MB | A few MB |
| Needs | Node.js only | Node.js and Rust |
| Web view | Its own Chromium, the same everywhere | The system's, so small differences between systems |
| Your own system code | JavaScript (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:
cd my-app
npx tauri icon build/icon.pngtauri 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
| Problem | Fix |
|---|---|
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 run | You 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 installed | Run npm install (or kreft add -D @tauri-apps/cli). |
| A white window in the packaged app | Run tauri:build again; the build must use --base ./. Check that dist/index.html exists. |
| API calls fail in the packaged app | The backend is not bundled. Set an absolute base for the API client, as for Electron. |
Linux build fails on webkit2gtk | Install the Linux libraries listed above. |
| Port 8000 is taken | Nothing 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
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| Flag | What it does |
|---|---|
--no-install | Do not run npm install. |
--force | Replace 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.
// 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:
// 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).
| # | Layer | Where | Applies to |
|---|---|---|---|
| 1 | Built-in defaults | the tables below | the runtime |
| 2 | Shared KreftJS configuration | kreftjs.config.json → "desktop" | both runtimes |
| 3 | Shared environment | KREFT_DESKTOP_WINDOW_WIDTH=1000 | both runtimes |
| 4 | Runtime configuration file | config/electron.config.js, config/tauri.config.js | one runtime |
| 5 | Runtime environment | KREFT_ELECTRON_WINDOW_WIDTH=1000, KREFT_TAURI_WINDOW_WIDTH=1000 (and the older ELECTRON_MENU, ELECTRON_DEVTOOLS) | one runtime |
| 6 | Command line | --set window.width=1000, --menu=visible, --devtools[=mode], --no-devtools | one 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.
{ "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
kreft electron:config # checks config/electron.config.js and prints the final settings
kreft tauri:config --json # the same for Tauri, as JSONdev 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:
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
| Setting | Default | Meaning |
|---|---|---|
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.development | true | DevTools are available while you work (F12 or Ctrl+Shift+I; Cmd+Option+I on macOS). |
devtools.openOnStart | false | …but closed when the window opens. Set it to true to open them by themselves. |
devtools.production | false | No 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 security | contextIsolation: true, sandbox: true, nodeIntegration: false, webSecurity: true | Pages cannot reach Node.js. Turning one off prints a note. |
security.blockNewWindows | true | A 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.enabled | false | A page may not show notifications until you allow it. |
window | 1200 × 800, minimum 800 × 600 | Resizable, 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.
| Option | Runtime | Default | What it does |
|---|---|---|---|
app.name | both | null | The name people see. Default: the "productName" or "name" in package.json. |
app.id | both | null | The reverse-domain id, for example "com.acme.notes". Default: com.kreftjs. followed by the lowercase name. |
app.version | both | null | The version number. Default: the "version" in package.json. |
app.description | both | null | A one-line description. Default: the "description" in package.json. |
app.author | both | null | Who makes the app. Default: the "author" in package.json. |
app.homepage | both | null | The web address of the app. Default: the "homepage" in package.json. |
app.copyright | both | null | The copyright line shown in the installer and the About box. |
#window
How the main window looks and behaves.
| Option | Runtime | Default | What it does |
|---|---|---|---|
window.title | both | null | The window title. Default: the app name. |
window.width | both | 1200 | Width in pixels. From 200 to 16000. |
window.height | both | 800 | Height in pixels. From 150 to 16000. |
window.minWidth | both | 800 | The window cannot be made narrower than this. From 0 to 16000. |
window.minHeight | both | 600 | The window cannot be made lower than this. From 0 to 16000. |
window.maxWidth | both | null | The window cannot be made wider than this. null: no limit. From 200 to 32000. |
window.maxHeight | both | null | The window cannot be made higher than this. null: no limit. From 150 to 32000. |
window.x | both | null | Distance from the left edge of the screen. null: the system chooses (or the window is centered). From -32000 to 32000. |
window.y | both | null | Distance from the top edge of the screen. null: the system chooses (or the window is centered). From -32000 to 32000. |
window.center | both | true | Open the window in the middle of the screen (ignored when x and y are set). |
window.resizable | both | true | Let people resize the window. |
window.fullscreen | both | false | Open the window in full screen. |
window.maximized | both | false | Open the window maximized. |
window.alwaysOnTop | both | false | Keep the window above all others. |
window.frame | both | true | Draw the system title bar and border. false: a window without them. |
window.transparent | both | false | A see-through window background (the page must draw its own background). |
window.backgroundColor | both | '#ffffff' | The colour shown before the page has drawn, as #rrggbb. |
window.theme | both | 'system' | The look of the window frame and the system dialogs. Values: system, light, dark. |
window.skipTaskbar | both | false | Keep the window out of the taskbar or dock. |
window.showOnReady | Electron | true | Show the window only when the page is ready, so it never opens as a white flash. |
#menu
The native application menu.
| Option | Runtime | Default | What it does |
|---|---|---|---|
menu.visibility | both | '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.template | both | null | Your own menu, as a list of top-level entries with a submenu. null: the default menu of the runtime. |
#contextMenu
The right-click menu.
| Option | Runtime | Default | What it does |
|---|---|---|---|
contextMenu.enabled | both | true | Allow the right-click menu. false: right-click does nothing. |
contextMenu.items | Electron | ['copy', 'cut', 'paste', 'selectAll'] | The entries of the right-click menu on text. |
contextMenu.inspectElement | Electron | true | Add "Inspect element" when DevTools are allowed. |
#devtools
The developer tools.
| Option | Runtime | Default | What it does |
|---|---|---|---|
devtools.development | both | true | Allow DevTools while you work (kreft electron:dev, kreft tauri:dev). |
devtools.production | both | false | Allow DevTools in the installed app. Keep it false unless you need to debug a release. |
devtools.openOnStart | both | false | Open DevTools by themselves when the window opens (only where they are allowed). |
devtools.mode | both | Electron 'right', Tauri 'detach' | Where DevTools open. Tauri can only open them in their own window. Values: Electron right, bottom, left, detach; Tauri detach. |
devtools.shortcut | both | true | F12 and Ctrl+Shift+I (Cmd+Option+I on macOS) toggle DevTools where they are allowed. |
#webview
The web page inside the window.
| Option | Runtime | Default | What it does |
|---|---|---|---|
webview.zoomFactor | both | 1 | The page zoom. 1 is 100 %. From 0.25 to 5. |
webview.userAgent | both | null | Text sent to servers as the browser name. null: the default of the runtime. |
webview.spellcheck | Electron | false | Underline misspelled words in text fields. |
webview.backgroundThrottling | Electron | true | Slow the page down when the window is hidden. |
webview.openExternalLinksInBrowser | both | true | A link to another site opens in the system browser, not in the app window. |
webview.allowedNavigation | both | [] | 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.
| Option | Runtime | Default | What it does |
|---|---|---|---|
security.csp | both | null | The Content-Security-Policy of the pages, for example "default-src 'self'". null: none is added. |
security.blockNewWindows | both | true | Pages cannot open new windows. |
security.contextIsolation | Electron | true | Keep the page and the preload script in separate JavaScript worlds. |
security.sandbox | Electron | true | Run the page in the operating system sandbox. |
security.nodeIntegration | Electron | false | Give the page access to Node.js. Leave it false: any script on the page could then run programs on the computer. |
security.webSecurity | Electron | true | Keep the same-origin policy of the browser. |
security.allowRunningInsecureContent | Electron | false | Let an https page load http scripts. |
security.permissions | Electron | [] | Browser permissions the page may get, for example "geolocation", "media", "clipboard-read". Notifications are allowed by notifications.enabled. |
security.capabilities | Tauri | [] | 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.globalTauri | Tauri | true | Put the Tauri API on window.__TAURI__. |
#tray
The system tray icon.
| Option | Runtime | Default | What it does |
|---|---|---|---|
tray.enabled | both | false | Show an icon in the system tray (the menu bar on macOS). |
tray.icon | both | null | A PNG file, relative to the project. null: the app icon. |
tray.tooltip | both | null | Text shown when the mouse rests on the icon. null: the app name. |
tray.closeToTray | both | false | Closing the window hides it; the app keeps running in the tray. Choose "Quit" in the tray menu to leave. |
tray.clickAction | both | 'toggle' | What a click on the tray icon does. Values: toggle, show, none. |
tray.menu | both | [{'label':'Show', 'action':'show'}, {'type':'separator'}, {'label':'Quit', 'action':'quit'}] | The entries of the tray menu. |
#notifications
System notifications.
| Option | Runtime | Default | What it does |
|---|---|---|---|
notifications.enabled | both | false | The page may show system notifications. In Tauri this adds the notification plugin (a crate and a permission). |
#updates
Updates.
| Option | Runtime | Default | What it does |
|---|---|---|---|
updates.enabled | both | false | Look for new versions of the app. |
updates.url | both | null | The https address of the folder that holds the update files (Electron: latest.yml and the installers; Tauri: the update JSON). |
updates.channel | both | 'latest' | The release channel, like "latest" or "beta". |
updates.checkOnStart | both | true | Look for an update each time the app starts (installed app only). |
updates.autoDownload | Electron | false | Download an update without asking. |
updates.pubkey | Tauri | null | The public key that update files are signed with (made by "npx tauri signer generate"). |
#packaging
How the installers are made.
| Option | Runtime | Default | What it does |
|---|---|---|---|
packaging.icon | both | 'build/icon.png' | The app icon, a square PNG (1024×1024 is best), relative to the project. |
packaging.category | both | null | The category in app stores and menus, like "public.app-category.productivity" (macOS) or "Utility" (Linux). null: the default of the runtime. |
packaging.electron.outputDir | both | 'dist-electron' | The folder the installers are written to. |
packaging.electron.mac | both | ['dmg', 'zip'] | Installers to make for macOS. |
packaging.electron.win | both | ['nsis', 'portable'] | Installers to make for Windows. |
packaging.electron.linux | both | ['AppImage', 'deb', 'rpm'] | Installers to make for Linux. |
packaging.electron.asar | both | true | Pack the app files into one archive. |
packaging.electron.compression | both | 'normal' | How much the installer is compressed. Values: store, normal, maximum. |
packaging.electron.files | both | ['dist/**/*', 'electron/**/*', 'package.json'] | The files that go into the app (build/icon.png and the tray icon are added). |
packaging.electron.extraResources | both | [] | Extra files copied next to the app, relative to the project. |
packaging.tauri.targets | both | null | Installers to make. null: all that fit the system you build on. |
packaging.tauri.resources | both | [] | Extra files that go into the app, relative to src-tauri/. |
packaging.tauri.macMinimumSystemVersion | both | '10.15' | The oldest macOS the app runs on. |
packaging.tauri.windowsWebviewInstall | both | '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.
| Option | Runtime | Default | What it does |
|---|---|---|---|
advanced.builder | Electron | { … } | Merged into the electron-builder configuration. Use it for options this file does not have. |
advanced.tauriConf | Tauri | { … } | 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:
| Electron | Tauri | |
|---|---|---|
| What the settings become | electron/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 roles | the shared ones, and reload, forceReload, toggleDevTools, zoomIn, zoomOut, resetZoom | the shared ones only (undo, redo, cut, copy, paste, selectAll, minimize, close, quit, fullscreen, about) |
| Right-click menu | You choose the entries (contextMenu.items) | The web view's own menu; only on or off (contextMenu.enabled) |
| DevTools | right, bottom, left or detached; can be switched off in development | detached window only; a development build always has them (devtools.development must be true) |
| Permissions | security.permissions (browser permissions) | security.capabilities (Tauri permissions); notifications and updates add theirs by themselves |
| Notifications | a permission, and kreftDesktop.notify(title, body) | the tauri-plugin-notification crate, added by notifications.enabled (use its JavaScript API in the page) |
| Updates | electron-updater (install it: kreft add electron-updater) and a generic feed at updates.url | tauri-plugin-updater, a signed update JSON at updates.url and the public key in updates.pubkey |
| Installers | packaging.electron (targets per system, asar, compression…) | packaging.tauri (targets, resources, WebView2 install mode…) |
| A way out | advanced.builder (merged into the electron-builder configuration) | advanced.tauriConf (merged into tauri.conf.json) |
| Page API | window.kreftDesktop | window.__TAURI__ (security.globalTauri) |
| Events to the page | kreftDesktop.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):
// 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:
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):
// 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:
// 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:
// 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 theapp: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 callskreft_generated::apply. Calling.setup(…)or.invoke_handler(…)on the builder replaces what was set before, so callkreft_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:
/** @type {import('kreftjs/desktop').TauriConfig} */
module.exports = { devtools: { mode: 'detach' } }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'(orELECTRON_MENU=show) to bring it back. ELECTRON_MENUandELECTRON_DEVTOOLSstill work, as layer 5.- The
buildblock ofpackage.jsonis ignored. Installers are made frompackagingandappinconfig/electron.config.js. Move yourappId,productNameand targets there (or intoadvanced.builder). electron/main.jsandpreload.jsare generated. A hand-writtenmain.jsis saved asmain.js.bakand replaced the next time you run a command; move your code toelectron/custom.js.src-tauri/tauri.conf.json,capabilities/default.jsonandsrc/kreft_generated.rsare written from the config file every time. Put options this file lacks inadvanced.tauriConf. YourCargo.tomlkeeps your own dependencies; Kreft only writes the lines between its twokreft-generatedcomments.window.widthandheightare 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
| Problem | Fix |
|---|---|
unknown option | A name is misspelled or in the wrong group. The message lists the valid names and suggests the closest. |
is not supported by Tauri / by Electron | The option belongs to the other runtime. The message says what to use instead (see the table above). |
x and y go together | Set both window.x and window.y, or neither. |
config/electron.config.js could not be loaded | A syntax error, or the wrong module style: module.exports in a "type": "module" project (use export default or .cjs). |
| My change has no effect | Restart 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 missing | Start 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 settings | The note says to add mod kreft_generated; and kreft_generated::apply(tauri::Builder::default()). |
updates.pubkey is required | Tauri verifies every update. npx tauri signer generate -w ~/.tauri/app.key, then put the public key in the file. |
| Shortcuts (F12) do nothing | DevTools 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
| Target | Shell | Add it | Run it | Package it | Status |
|---|---|---|---|---|---|
| Web application | the browser | kreft new my-app | kreft dev | kreft build | Tested |
| macOS (Electron) | Electron | kreft add electron | kreft electron:dev | kreft electron:build --mac | Tested |
| Linux (Electron) | Electron | kreft add electron | kreft electron:dev | kreft electron:build --linux | Not tested here |
| Windows (Electron) | Electron | kreft add electron | kreft electron:dev | kreft electron:build --win | Not tested here |
| macOS (Tauri) | Tauri | kreft add tauri | kreft tauri:dev | kreft tauri:build | Tested |
| Linux (Tauri) | Tauri | kreft add tauri | kreft tauri:dev | kreft tauri:build | Not tested here |
| Windows (Tauri) | Tauri | kreft add tauri | kreft tauri:dev | kreft tauri:build | Not tested here |
| iOS | Capacitor | kreft new my-app --mobile | kreft mobile:run --ios | kreft mobile:release --ios | Not tested here |
| Android | Capacitor | kreft new my-app --mobile | kreft mobile:run --android | kreft mobile:release --android | Tested |
| HarmonyOS | ArkTS web view | kreft new my-app --harmony | kreft harmony:open (DevEco Studio) | kreft mobile:release --harmony | Not tested here |
| Android TV, tvOS, webOS, Tizen | Coming 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 only | The web. Nothing to add. |
| A desktop app, and I want the page to look the same on every system | Electron. 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 Rust | Tauri. It uses the system's web view. Installers are a few megabytes. Needs Rust. |
| An app in Google Play | Android. |
| An app in the App Store | iOS. Needs a Mac with Xcode and a paid Apple Developer account. |
| An app for Huawei phones and tablets | HarmonyOS. 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
| Target | You need installed |
|---|---|
| Web | Node.js 22.5 or newer |
| Electron | Node.js (Electron and electron-builder come with kreft add electron) |
| Tauri | Node.js and Rust; on Linux the WebKitGTK libraries; on Windows the Visual Studio C++ build tools |
| Android | Android Studio and a Java from 21 to 23 |
| iOS | A Mac with Xcode |
| HarmonyOS | DevEco 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:initsets that up so the website keeps its normal addresses. - The native bridge differs. Electron gives pages
window.kreftDesktop; Tauri giveswindow.__TAURI__; the phone apps giveKreftjs.native(camera, files, share, haptics…). Write the page once and ask which one it is running in:
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 TauriHarmonyOS 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:
| Target | Plan |
|---|---|
| Android TV | The Android app, with a remote-control (D-pad) focus ring and a TV layout kit |
| Apple tvOS | A tvOS shell around the same pages |
| LG webOS | A packaged web app for LG TVs |
| Samsung Tizen | A 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 app | kreft add electron, kreft add tauri, or kreft add electron tauri |
| Check the desktop settings | kreft electron:config, kreft tauri:config |
| Run a desktop app | kreft electron:dev, kreft tauri:dev |
| Make desktop installers | kreft electron:build [--mac] [--win] [--linux], kreft tauri:build |
| Add phone support | kreft new my-app --mobile, or kreft mobile:init |
| Run on a phone or emulator | kreft mobile:run --android, kreft mobile:run --ios, kreft mobile:dev |
| Add HarmonyOS | kreft new my-app --harmony, or kreft harmony:init |
| Build and open HarmonyOS | kreft harmony:build --api-url https://…, kreft harmony:open |
| Release a phone app | kreft mobile:release --android, --ios, --harmony; the steps are in Publishing your app to Google Play and the App Store |