Developing Electron Desktop

Developing the Electron desktop app

apps/desktop runs the server and the client in one Electron process: the main process boots @triliumnext/core + the Express app from @triliumnext/server, and the renderer is the ordinary apps/client bundle. There is no HTTP between them — see "How the renderer reaches the server" below. apps/desktop/src/main.ts is the entry point; services/window.ts creates windows and owns the window/spellcheck IPC.

Layout

apps/desktop/
  src/main.ts                    # startup: platform provider, core init, Express app, windows, tray, IPC setup
  src/preload.ts                 # the ONLY bridge renderer ↔ main (contextBridge → window.electronApi)
  src/protocol.ts                # trilium-app:// scheme → dispatch into Express in-process
  src/ipc_messaging_provider.ts  # replaces the WebSocket with ipcMain/webContents.send
  src/platform_provider.ts       # DesktopPlatformProvider (isElectron, getEnv, crash)
  src/services/window.ts         # BrowserWindow creation, webPreferences, window/spellcheck/nav IPC
  src/services/*.ts              # one module per concern: tray, printing, dialog, import, export,
                                 #   restore, shell, auto_launch, backup_passphrase, security_settings,
                                 #   custom_dictionary, onenote (+ loopback_oauth), referer, request,
                                 #   startup_metrics, web_contents_security
  src/*.spec.ts, services/*.spec.ts   # vitest, `pnpm --filter desktop test`
  spec/build-checks/artifacts.spec.ts # verifies the built dist
  e2e/                           # Playwright against the built app (`pnpm --filter desktop e2e`)
  scripts/build.ts               # esbuild bundle + asset copy into dist/
  electron-forge/                # packaging (forge.config.ts, icons, dmg, portable/safe-mode launchers)
                                 # flip-fuses.ts + trim-locales.ts are ALSO run as scripts by the
                                 # Flathub manifest — see the packaging-for-flathub skill before editing

Process and security model

• nodeIntegration: false, contextIsolation: true, webviewTag: true on every window (services/window.ts). The renderer has no Node, no require("electron"), no @electron/remote (removed — never reintroduce it). Everything crosses through the preload bridge.
• web_contents_security.ts vets every <webview> in will-attach-webview and decides window.open: the app shell's root URL becomes an extra window in the opener's renderer process (that is how the client opens new windows — no IPC channel), everything else is denied and allow-listed URLs are routed to the OS. If a new feature needs a popup or a webview privilege, change it there — never relax webPreferences at the call site.
• Main-process handlers validate their input and never trust a path from the renderer: OS pickers run in the main process (dialog.ts, import.ts, restore.ts) and hand back a location the user chose; import.ts mints single-use access grants rather than accepting a path; shell.ts gates every channel with a validator that throws. Follow the same shape for anything that touches the filesystem or the OS.
• Secrets stay out of the DB where they must: security_settings.ts reads data_dir/security.json, backup_passphrase.ts uses the OS keyring — the passphrase must not travel inside the backup it protects.
• services/request.ts (ElectronRequestProvider) uses Electron's net so sync honours the system proxy; referer.ts keeps hosts that require an http(s) Referer working from the trilium-app:// origin.

How the renderer reaches the server

• The UI loads from trilium-app://app/, a privileged custom scheme (protocol.ts). registerTriliumAppScheme() must run before app.ready (Electron ignores registerSchemesAsPrivileged afterwards and navigation aborts with (blocked:origin)); setupTriliumAppProtocol(expressAppPromise) installs the handler that synthesises a Node request/response and dispatches through the real Express app — session, CSRF, multer and error middleware all run. Requests arriving before the server is built simply wait on the promise. apps/server/src/services/electron_request.ts tags them so auth/CSRF middleware can tell them from external TCP traffic. The same two functions are reused by apps/edit-docs.
• WebSocket is replaced by IPC: ipc_messaging_provider.ts implements MessagingProvider over webContents.send / ipcMain.on, one client per webContents.id; the client side picks it up through window.electronApi.ws (apps/client/src/services/ws.ts). Don't open a TCP WebSocket from desktop code.
• Window creation is gated on core init, not full server startup, so the renderer spins up while Express is still building (coreInitializedPromise / expressAppPromise in main.ts).

The main() prologue runs before the database

Everything from the top of main() down to dbProvider.loadFromFile(…) runs before app.on("ready") and long before initializeCore() wires core's SQL layer. Chromium switches (app.commandLine.appendSwitch, app.disableHardwareAcceleration) must be applied before ready, which forces that shape — current readers are lang via getElectronLocale(), smoothScrollEnabled (#10559) and hardwareAccelerationEnabled (#10572). Three rules hold in that window:

• options.getOptionOrNull() always returns null there. It falls back to getSql(), which throws before the provider is wired, so an option-derived switch silently takes its default (#10559). Read pre-ready values with readDbOption(dbProvider, name) instead.
• Keep the prologue await-free. app, config and dataDirs are static imports precisely so ready cannot fire before the database is open. Adding an await — including a await import(…) for something already statically available — reintroduces the race that lands a switch too late.
• Open the database once. The BetterSqlite3Provider the switches read from is the same instance handed to initializeCore({ dbConfig: { provider } }); don't open a second connection. The single-instance lock check stays before the open, so a second launch exits without touching the file.

Adding an Electron API (renderer → main)

Four files, always together:

1. Interface — add the method to the right group interface in packages/commons/src/lib/electron_api_interface.ts (ElectronWindowApi, ElectronShellApi, ElectronPrintingApi, …; the groups are listed on ElectronApi at the bottom of the file, each with a one-line purpose). New concern → new ElectronXxxApi interface and a new key on ElectronApi. Doc-comment the method: the client only sees this file.
2. Preload — implement it in apps/desktop/src/preload.ts inside the matching group of the contextBridge.exposeInMainWorld("electronApi", { … } satisfies ElectronApi) literal. satisfies makes the typecheck fail until preload matches the interface. Keep the preload thin: marshal arguments to ipcRenderer.send / invoke / sendSync; no logic.
3. Handler — register the ipcMain handler in the service module that owns the concern (services/shell.ts, services/printing.ts, …, each with a setupXxxHandlers() called from main.ts), or in setupWindowing() in services/window.ts for window/spellcheck/navigation. Channel names are kebab-case verbs (open-external, set-full-screen, backup-passphrase-set). Pick the IPC style by shape:
   • ipcMain.on(channel, handler) — fire-and-forget (ipcRenderer.send);
   • ipcMain.handle(channel, handler) — async request/response (ipcRenderer.invoke);
   • ipcMain.on + event.returnValue = … — synchronous query (ipcRenderer.sendSync); use sparingly, it blocks the renderer. Main → renderer events go the other way: webContents.send(channel, …) in main, an ipcRenderer.on subscription exposed as onXxx(callback) in preload.
4. Tests — apps/desktop/src/preload.spec.ts (asserts the exposed API shape and that each method sends/invokes the right channel; extend the exposedApi assertions) and the owning service's *.spec.ts for the handler.

Then call it from the client as window.electronApi?.group.method() — always optional-chained, since the same client runs in the browser. window.electronApi is declared in apps/client/src/types.d.ts; gate desktop-only UI on isElectron() from apps/client/src/services/utils.ts (server side: utils.isElectron).

A new handler module is dead until main.ts calls its setupX()

ipcMain.on/handle only registers when the module's setup function actually runs, and there is no startup error if you forget. The symptom is silent at the source: a send channel no-ops, and a sendSync channel hangs the renderer forever, because synchronous IPC blocks the whole renderer process waiting for a reply that never comes. The setup calls live in one block in main.ts (plus ipcMessaging.init() further down). Adding a module means adding the call there.

Which module owns my channel?

The preload API group name does not map 1:1 to a handler module — infer from this table, not from the group:

Note the splits that defeat guessing by group: spellcheck's add-word-to-dictionary is in custom_dictionary.ts while the spellchecker-language channels are in window.ts, and the clipboard handlers live in window.ts, not a clipboard module.

Transport must match the handler kind

Mismatch it and the failure is silent or fatal, never a clear error:

Multiplexed channel: navigation-history is one channel serving several preload methods via a method-name first argument and an event.returnValue switch.

Crash-safety

An unhandled throw inside an ipcMain.on listener crashes the entire main process — there is no renderer-side rejection to catch it. shell.ts carries this warning verbatim next to open-custom. Wrap every handler body:

electron.ipcMain.on("my-channel", (_event, arg: string) => {
    try {
        doThing(validateArg(arg));
    } catch (e) {
        getLog().error(`my-channel failed: ${coreUtils.safeExtractMessageAndStackFromError(e)}`);
    }
});

For an ipcMain.handle whose contract is Promise<string>, the catch should also return the error string, since the renderer awaits it — that is what open-path/open-file-url do.

Check the wiring with ipc-parity.mjs

A direction-aware parity diff across interface ↔ preload ↔ ipcMain handlers ↔ spec. Run it after wiring a channel, or to audit drift:

node .claude/skills/developing-electron-desktop/scripts/ipc-parity.mjs

It reports renderer→main channels with no handler (these hang or no-op), transport/handler-kind mismatches, handler modules whose setupX() is never called, handlers with no preload caller (print-note/export-as-pdf are known legacy orphans), and preload channels with no preload.spec.ts assertion. It whitelists push-only channels and is channel-granular, so the multiplexed navigation-history doesn't false-positive. Exit code 1 on a fatal finding.

Validating untrusted renderer input

The renderer is XSS-reachable, so it is untrusted. Every fs/shell/url channel validates in the main process and throws on violation. The five validators in apps/desktop/src/services/shell.ts are exported and unit-tested:

• validateOpenExternalUrl — scheme allowlist from SHELL_OPEN_EXTERNAL_PROTOCOLS (commons); blocks Follina (ms-msdt:/search-ms:), the smb:/ldap: NTLM leak, and file:/data:/jar:.
• validateOpenPath / validateOpenCustomPath — canonicalize and sandbox to the data dir / tmp dir; implicitly blocks UNC paths and traversal; reject null bytes and nonexistent files.
• validateOpenFileUrl — require file: with an empty hostname (blocks the file://attacker/share UNC NTLM leak); normalize file://C:/ → file:///C:/.
• validateDownloadUrl — same-origin lock by scheme + hostname + port. It cannot use URL.origin, because the custom scheme is opaque-origin ("null").

Add a validator for any new channel that takes a path, a URL, or anything else the main process will act on.