Introducing a new way to review your PRs.

Read the announcement

jgraph / drawio-desktop

Official electron build of draw.io

View on GitHub

10 documents · Updated Nov 16, 2026

docs / electron-shell

Electron Shell

Coverage: src/…/electron.js, src/…/electron-preload.js, src/…/disableUpdate.js, preload.js, package.json at source commit 0623fb3c1523639b06600d5c33e3a127bf82aa1c.

Overview

The desktop shell is an Electron ES-module app whose entry point is declared by package.json as both main and exports: src/…/electron.js. package.json also defines npm start as electron ., release scripts for electron-builder, and pins the app to Node >=22.12.0 with Electron in dev dependencies. preload.js at the repository root is only a small legacy/debug preload that logs and installs window.PreApp; the actual application windows use src/…/electron-preload.js.

src/…/electron.js owns process-wide startup, update policy, window creation, menu wiring, command-line export mode, and all renderer-facing IPC. It initializes electron-store defensively and keeps user settings there, including spellcheck, backup writing, Google Fonts enablement, update preferences, last window bounds, one-shot migrations, and a persisted bounded set of user-authorized filesystem paths (blessedPaths). src/…/disableUpdate.js currently exports disableUpdate() as false, so update behavior is controlled by platform/install detection plus DRAWIO_DISABLE_UPDATE or --disable-update in src/…/electron.js.

Window creation is centralized in createWindow() in src/…/electron.js. It restores the last saved bounds from electron-store, sanitizes them against current displays, applies dark/light splash background, and creates a BrowserWindow loading drawio/…/index.html as a file: URL with query parameters from URL/config helpers. Every editor window uses src/…/electron-preload.js, contextIsolation: true, nodeIntegration: false, webviewTag: false, and webSecurity: true. The preload exposes only a narrow window.electron bridge: request/response IPC through rendererReq/mainResp, message listeners, one-shot listeners, and generic sends. It also exposes window.process.type and window.process.versions, seeds the defaultAdaptiveColors migration into localStorage when the main process passes --initial-adaptive-colors=..., and blocks about: navigations in the isolated world because those navigations do not reach main-process will-navigate.

The lifecycle starts in app.whenReady() in src/…/electron.js. Before creating windows, it installs a response-header CSP on the default session and blocks file:// requests outside the packaged webapp directory. It registers global IPC handlers that should not be per-window (openDevTools, newfile), parses CLI arguments, handles --export, --version, and --help, and otherwise acquires a single-instance lock. The first visible window is created, then the shell waits for both Electron did-finish-load and the renderer's app-load-finished IPC before sending args-obj to the renderer. The same two-event handshake is reused for second-instance launches and macOS open-file events so file association paths are delivered after the editor is ready.

Renderer-originated IPC is gated in src/…/electron.js by validateSender(frame), which accepts only frames whose URL starts with the local webapp codeUrl. The main request multiplexer listens on rendererReq and switches on actions for file save/read/draft/backup, open/save dialogs, clipboard, window actions, external links, file watching, local font enumeration, fullscreen state, and update state. File dialogs and command-line/file-association opens call blessPath(), and subsequent filesystem IPC must pass assertReadablePath() or assertWritablePath(). These checks canonicalize real paths, reject app-bundle paths and userData writes, allow draft/backup siblings of blessed files, and optionally allow configuration-named read paths after a main-process confirmation dialog via ConfigPathGrants.

The app shell also orchestrates desktop UI behavior. On macOS, src/…/electron.js builds an application menu with app/about/support/update items, zoom actions, edit roles, and quit/hide roles; on Windows and Linux it hides the application menu. It tracks all windows in windowsRegistry, persists size on close, forwards maximize/unmaximize/resize events to the renderer, intercepts Ctrl/Cmd+Shift+V for paste-without-formatting, recreates a window on macOS dock activation, and keeps macOS alive until explicit quit while quitting immediately when all windows close on other platforms. Closing a window asks the renderer whether it is modified; if so, main shows a native save/discard/cancel dialog and then coordinates saveAndClose, draft removal, or destroy over IPC.

Update flow is process-wide in src/…/electron.js. At startup it computes updateMode from disableUpdate(), environment, CLI flags, platform/install mode, and electron-updater support. The auto-updater is wrapped by safeUpdaterCall() and safeUpdaterListener() so sync throws and rejected promises route to notifyUpdateFailure(). Update checks can be manual (checkForUpdates IPC/menu) or background (checkForUpdatesIfDue()), with electron-store controlling automatic checks and interval. In auto mode the shell can download silently and broadcast updateState to editor windows; in notify mode it opens a release URL. Downloaded updates expose a renderer/menu restart path, close windows first so unsaved-change prompts run, then call quitAndInstall().

CLI export mode is also implemented in src/…/electron.js, before the single-instance GUI path. When --export is parsed, the shell creates hidden windows using the same secure preload/webPreferences, validates inputs and output targets, scans directories without following symlinks, imports VSDX through a hidden importer window, and renders exports through export3.html in exportDiagram(). Exported PNG/PDF/SVG/XML handling, PDF annotation/metadata embedding, and print retry behavior live in this same file, so the shell is not just the GUI bootstrapper; it is also the trusted native side for rendering, filesystem writes, printing, and clipboard operations.

Coupling

  • If src/…/electron.js changes webPreferences.preload, IPC channel names, or the rendererReq/mainResp message shapes, update src/…/electron-preload.js at the same time. The preload owns request IDs, callback dispatch, and the special multi-callback watchFile path, while the main process assumes the renderer sends args.action and args.reqId on rendererReq.
  • If the local webapp path calculation in src/…/electron.js changes (codeDir, codeUrl, or the loaded index.html/export3.html/vsdxImporter.html URLs), verify validateSender(), the session file:// allowlist, and the CSP still agree. A mismatch blocks legitimate app resources or silently drops IPC from the renderer.
  • If a new renderer-visible filesystem action is added to the rendererReq switch in src/…/electron.js, route it through assertReadablePath() or assertWritablePath() as appropriate and add user-intent blessing through open/save dialogs, argv/file association, or a main-process confirmation. validateSender() only proves the request came from the app page; it does not protect against malicious diagram content executing inside that page.
  • If update settings or UI change in src/…/electron.js, keep the macOS menu items, renderer IPC (checkForUpdates, installUpdate, toggleAutoUpdate, getUpdateState), and electron-store keys (dontCheckUpdates, updateCheckIntervalHours, lastUpdateCheck) aligned. The menu visibility and renderer notices are both driven by setUpdateState().
  • If command-line flags or package entry points change, update both package.json and the parse/dispatch flow in src/…/electron.js. package.json launches electron ., while src/…/electron.js handles --export, --version, --help, --disable-update, --no-silent-update, --disable-acceleration, and zoom/export options.

Risks

  • src/…/electron.js has multiple global ipcMain.once('app-load-finished', ...) listeners for first window, second-instance windows, and macOS open-file, with TODO comments noting that quickly creating multiple windows can catch another window's load event. If this routing crosses windows, a file path from argv/file association can be sent to the wrong renderer or not sent at all.
  • Navigation controls are split between src/…/electron.js and src/…/electron-preload.js: main cancels will-navigate, while the preload separately blocks about: navigation because Chromium does not surface those to main. If the preload is removed or not loaded for a window, an about:blank self-navigation can replace the editor despite the main-process navigation guard.
  • The filesystem trust boundary in src/…/electron.js depends on blessPath(), native realpath canonicalization, persisted blessedPaths, and the readable/writable assertions staying in sync. Comments cite prior issues around network/subst drive realpaths and legacy recent/custom-library migrations; if one path source is blessed lexically but checked by a different canonical form, legitimate saves/reads can fail, while weakening the check can let renderer-controlled content read or write outside user-authorized files.
  • src/…/electron.js registers some IPC listeners globally and historically moved handlers out of per-window setup because per-window handlers leaked and later crashed on openDevTools. New global listener additions must remove one-shot listeners on all completion/error paths, especially export/import listeners, or a later hidden export/window can receive stale replies.