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 / packaging-and-installers

Packaging and Installers

Overview

Desktop releases are driven from the root package.json scripts and a family of platform-specific Electron Builder configs. package.json defines the Electron app entrypoint (src/…/electron.js), requires Node >=22.12.0, pins the release version, and exposes the packaging commands: release-win, release-win-arm64, release-appx, release-linux, and release-snap. package-lock.json locks the packaging toolchain versions used by those commands, including electron-builder, electron, @electron/fuses, @electron/notarize, and quicklookjs. .nvmrc currently says 20, so local shell selection can differ from the engine declared in package.json and package-lock.json.

All electron-builder*.json configs package the app as asar, write artifacts under ./dist/, set npmRebuild to false, and use the same inclusion/exclusion policy for packaged files. The policy starts with **/*, excludes webapp/server-only material such as WEB-INF, most stencils/shapes, large draw.io editor source trees, source maps, and unused @cantoo/pdf-lib subtrees, then explicitly keeps drawio/src/main/webapp/js/diagramly/{ElectronApp,DesktopLibrary}.js. The common file associations are for .drawio, .vsdx, and Mermaid (.mmd/.mermaid) files, with extra macOS bundle metadata in electron-builder-linux-mac.json for the com.jgraph.drawio UTI and Finder document types.

Windows MSI/NSIS builds use electron-builder-win.json via npm run release-win. It publishes to GitHub, signs x64 NSIS and MSI artifacts, and signs bundled DLLs. NSIS is configured as a non-one-click, per-machine installer that lets users choose the install directory, does not run the app after install, and does not create a desktop shortcut. MSI uses ${productName}-${version}.msi-style naming and also disables run-after-finish and desktop shortcut creation. electron-builder-win-arm64.json is the ARM64 Windows config used by release-win-arm64; it publishes to GitHub channel latest-arm64, builds ARM64 NSIS plus a portable no-installer artifact, and uses the same signing hook and file associations as the x64 Windows config.

Windows code signing is delegated to build/sign-trusted.mjs through win.signtoolOptions.sign in the Windows configs. Electron Builder invokes it for each signable Windows binary: the unpacked app executable, installers, and .dll files listed through signExts. The hook uses Azure Trusted Signing metadata for endpoint https://weu.codesigning.azure.net, account drawio-signing, and profile drawio-codesign, then calls signtool.exe with SHA-256 digest and timestamping. It requires TRUSTED_SIGNING_DLIB_PATH, SIGNTOOL_PATH, and Azure credential environment variables supplied by CI; setting DRAWIO_UNSIGNED=true skips this signing path for personal/fork builds.

electron-builder-appx.json is a separate Store package config used by npm run release-appx. It builds only an x64 AppX/MSIX target, publishes never from the npm script despite the config containing a GitHub provider, and declares Store identity data under appx: display name draw.io Diagrams, identity name draw.io.draw.ioDiagrams, publisher CN=9E628CCB-BE04-4557-A5A8-81EC34B09733, and Windows version bounds 10.0.17763.0. Store-specific tile/logo images live under build/appx/.

Linux and macOS share electron-builder-linux-mac.json, run by npm run release-linux. For macOS it builds zip artifacts for x64 and arm64, and DMGs for x64, arm64, and universal. Hardened runtime is enabled, Gatekeeper assessment is disabled during build, and both app and inherited entitlements point at build/entitlements.mac.plist, which allows unsigned executable memory and JIT. build/notarize.mjs runs as afterSign on Darwin, adds and signs a Quick Look preview extension, then notarizes with @electron/notarize using APPLEID, APPLEIDPASS, and APPLE_TEAM_ID unless DRAWIO_UNSIGNED=true is set.

The macOS Quick Look path in build/notarize.mjs copies node_modules/quicklookjs/dist/PreviewExtension.appex into Contents/PlugIns, replaces its preview.html with build/quicklook-preview.html, copies viewer-static.min.js from either build/viewer-static.min.js or drawio/…/viewer-static.min.js, and writes an Info.plist declaring support for the com.jgraph.drawio UTI. build/quicklook-preview.html loads viewer-static.min.js, obtains the previewed file from the Quick Look bridge, and renders it with GraphViewer.processElements(). The extension is signed with build/quicklook-entitlements.plist, which enables the app sandbox and network client entitlement; after signing the extension, build/notarize.mjs re-signs the outer .app so the bundle seal includes the plugin. Unsigned/ad-hoc builds get a deep ad-hoc re-sign instead of hardened runtime notarization.

build/dmg-hidden-files.mjs runs as beforePack for the shared Linux/macOS config but only mutates Darwin builds. It injects DMG contents entries that position hidden support files such as .background.tiff, .VolumeIcon.icns, and .DS_Store below the visible installer window. When dmg.contents is absent, it also reconstructs Electron Builder's default app icon and /Applications link positions before adding the hidden-file positions.

Linux packaging in electron-builder-linux-mac.json builds AppImage, deb, and rpm artifacts for x64 and arm64. The executable name is drawio, category is Graphics, maintainer is draw.io <desktop@draw.io>, icons are read from ./build, and the desktop entry sets StartupWMClass to draw-io. AppImage compression is gzip, toolsets.appimage pins the AppImage toolset to 1.0.3, and the RPM target passes fpm options to disable build-id links and use a SHA-256 digest. Snap packaging is split into electron-builder-snap.json and npm run release-snap; it builds only a snap target, uses maintainer draw.io <snap@draw.io>, base core24, LXD-backed core24 builds, and plugs default, removable-media, and browser-support.

Every Electron Builder config runs build/fuses.mjs as afterPack. That hook computes the platform-specific executable path (drawio on Linux, app bundle on macOS, .exe on Windows), skips temporary universal macOS build directories, and flips Electron Fuse v1 options: disables ELECTRON_RUN_AS_NODE, disables NODE_OPTIONS and inspect CLI support, enables cookie encryption, enforces loading only from app.asar, keeps embedded asar integrity disabled, and disables the browser-process V8 snapshot fuse. For macOS arm64/universal builds it asks @electron/fuses to reset the ad-hoc Darwin signature after modifying the binary.

Packaging assets in build/ are mostly consumed by Electron Builder by convention. build/icon.icns, build/icon.ico, build/icon.png, build/icon.svg, and the size-specific PNGs provide application icons for platform packages, with Linux configs pointing at ./build so Electron Builder can pick the appropriate PNG sizes. build/create_macos_icon.sh is a helper for regenerating icon.icns from 1024x1024.png; it requires ImageMagick convert and macOS iconutil, applies macOS-style rounded corners/shadow, generates an iconset, converts it to .icns, and deletes the temporary iconset. build/icon.hqx and build/…/*.png are packaging assets for legacy/platform-specific icon needs rather than executable build hooks.

Coupling

  • If packaged webapp paths change, update the files arrays in every electron-builder*.json config together. All configs duplicate the same allow/deny list, so changing only one target can ship different app contents across Windows, macOS, Linux, Snap, or AppX.
  • If package.json changes the Electron Builder scripts or dependency versions, keep package-lock.json in sync. Release scripts call the locally installed electron-builder, @electron/fuses, @electron/notarize, and quicklookjs versions locked there.
  • If the supported Node version changes, check both package.json/package-lock.json and .nvmrc. The engine requires Node >=22.12.0 while .nvmrc selects Node 20, so local builds can use a different runtime than the package metadata expects.
  • If Windows signing behavior changes in electron-builder-win.json or electron-builder-win-arm64.json, verify build/sign-trusted.mjs and CI-provided TRUSTED_SIGNING_DLIB_PATH, SIGNTOOL_PATH, and Azure credential variables. The signing hook throws when the trusted signing DLL or signtool path is missing unless DRAWIO_UNSIGNED=true is explicitly set.
  • If macOS bundle identifiers, document UTIs, or file associations change in electron-builder-linux-mac.json, update the Quick Look Info.plist template inside build/notarize.mjs as well. The preview extension declares com.jgraph.drawio independently of Electron Builder's macOS extendInfo block.
  • If build/quicklook-preview.html starts depending on additional scripts/assets, update build/notarize.mjs to copy them into the .appex resources. The hook currently only copies the HTML file and viewer-static.min.js.
  • If Electron Fuses or signing order changes, test macOS packages through build/notarize.mjs. build/fuses.mjs modifies the packaged executable in afterPack, while build/notarize.mjs signs the Quick Look extension and re-signs the outer .app in afterSign; an ordering change can invalidate signatures.
  • If app icons are regenerated or renamed, verify the Electron Builder configs that rely on build/ by convention, the Windows/AppX assets under build/appx/, and build/create_macos_icon.sh's hard-coded 1024x1024.png source path.

Risks

  • electron-builder-linux-mac.json AppImage settings have recent revert/fix churn in history (Adds legacy fuse2 AppImage build, Reverts the legacy fuse2 AppImage build, and compression/toolset fixes). If toolsets.appimage, appImage.compression, or Linux targets change, AppImage runtime compatibility or startup on systems without expected FUSE support can regress.
  • Linux icon resolution is fragile around electron-builder-linux-mac.json, electron-builder-snap.json, and the build/*.png icon set: history contains repeated corrections and reverts for the Linux icon path. If linux.icon stops pointing at ./build or icon sizes are removed, deb/rpm/AppImage/Snap metadata can lose the expected application icon.
  • build/msi-project-created.mjs patches generated WiX XML with a regex to remove Icon="..." from shortcut elements. If Electron Builder changes the WiX shortcut shape, the hook may warn that no shortcut icons were found and MSI shortcuts can fall back to the cached Installer icon behavior described in issue jgraph/drawio-desktop#2487.
  • build/notarize.mjs depends on quicklookjs bundle layout and on finding viewer-static.min.js in either build/ or the draw.io webapp tree. If neither exists, the build continues without Quick Look setup, so macOS .drawio previews silently disappear even though notarization can still complete.