How Platform-Specific Build Configurations Work in drawio-desktop

The drawio-desktop repository uses separate JSON configuration files (electron-builder-*.json) to define platform-specific packaging rules for Windows, macOS, Linux, Snap, and AppX targets, each inheriting common settings while overriding platform-specific sections like win, mac, linux, snap, and appx.

The jgraph/drawio-desktop project leverages electron-builder to generate installable packages across multiple operating systems. Platform-specific build configurations allow the project to maintain a single codebase while applying distinct packaging rules, code signing requirements, and distribution formats for each target platform. These configurations are stored as individual JSON files in the repository root, each referenced by specific npm scripts during the release process.

Configuration File Structure

All platform-specific configurations follow the electron-builder JSON schema, combining shared top-level properties with targeted overrides.

Common Top-Level Fields

Every configuration file in the repository includes these core fields:

• appId: A unique reverse-domain identifier (com.jgraph.drawio-desktop) used for application registration and package naming
• productName: The display name shown to users ("draw.io Desktop")
• directories: Paths for build output and resources, typically { "output": "dist", "buildResources": "build" }
• files: Glob patterns defining which source files to bundle, such as ["src/main/**/*", "drawio/**/*", "!**/node_modules/**"]
• extraResources: Non-code assets shipped alongside the application, configured as [{ "from": "resources", "to": "resources", "filter": ["**/*"] }]
• afterSign: Hook scripts for post-signing operations like macOS notarization

Platform-Specific Sections

Each JSON file extends the base configuration with platform-specific objects:

• win: Windows executable targets, icon paths, and code signing settings
• nsis: Windows installer UI configuration (one-click vs. wizard)
• mac: macOS bundle settings including hardenedRuntime, entitlements, and notarize options
• linux: Linux package formats (AppImage, deb, rpm) and desktop integration metadata
• snap: Snap Store-specific confinement rules and package descriptions
• appx: Windows Store metadata including identityName and publisherDisplayName

Windows Build Configurations

The repository maintains three distinct Windows configurations to support different architectures.

64-bit Windows (electron-builder-win.json)

The primary Windows configuration targets x64 systems using NSIS installers:

{
  "appId": "com.jgraph.drawio-desktop",
  "productName": "draw.io Desktop",
  "directories": {
    "output": "dist",
    "buildResources": "build"
  },
  "files": [
    "src/main/**/*",
    "drawio/**/*",
    "!**/node_modules/**"
  ],
  "win": {
    "target": [
      {
        "target": "nsis",
        "arch": ["x64"]
      }
    ],
    "icon": "build/icons/win/icon.ico"
  },
  "nsis": {
    "oneClick": false,
    "allowElevation": true,
    "installerIcon": "build/icons/win/installer.ico"
  }
}

The win.target array specifies the NSIS format for x64 architectures, while nsis.oneClick: false creates a traditional installation wizard rather than a silent installer.

32-bit and ARM64 Variants

The electron-builder-win32.json and electron-builder-win-arm64.json files mirror the x64 structure but modify the arch array to target ia32 and arm64 respectively. These files reside in the repository root alongside the main Windows configuration, allowing parallel builds for legacy and modern Windows devices.

macOS and Linux Configuration (electron-builder-linux-mac.json)

This shared configuration handles both Unix-like platforms through distinct sections:

{
  "appId": "com.jgraph.drawio-desktop",
  "productName": "draw.io Desktop",
  "directories": {
    "output": "dist",
    "buildResources": "build"
  },
  "files": [
    "src/main/**/*",
    "drawio/**/*",
    "!**/node_modules/**"
  ],
  "mac": {
    "target": ["dmg", "zip"],
    "icon": "build/icons/mac/icon.icns",
    "hardenedRuntime": true,
    "gatekeeperAssess": false,
    "entitlements": "build/entitlements.mac.plist",
    "notarize": {
      "teamId": "..."
    }
  },
  "linux": {
    "target": ["AppImage", "deb", "rpm"],
    "category": "Graphics",
    "icon": "build/icons/png",
    "desktop": {
      "Name": "draw.io Desktop",
      "Comment": "Diagram drawing application",
      "Categories": "Graphics;Office;"
    }
  }
}

The mac section enables hardened runtime and notarization required for macOS Catalina and later, while the linux section generates multiple package formats suitable for different distributions.

Specialized Package Formats

Snap Configuration (electron-builder-snap.json)

The Snap configuration adds Linux containerization rules:

{
  "appId": "com.jgraph.drawio-desktop",
  "productName": "draw.io Desktop",
  "snap": {
    "confinement": "strict",
    "grade": "stable",
    "summary": "Desktop diagram editor",
    "description": "A powerful offline diagram editor based on draw.io, packaged as a Snap."
  },
  "extraResources": [
    {
      "from": "resources",
      "to": "resources"
    }
  ]
}

The confinement: "strict" setting ensures the application runs within the Snap sandbox, meeting requirements for the Ubuntu Snap Store.

Windows Store Configuration (electron-builder-appx.json)

For Microsoft Store distribution, the appx section defines Store-specific metadata:

{
  "appId": "com.jgraph.drawio-desktop",
  "productName": "draw.io Desktop",
  "appx": {
    "identityName": "JGraph.drawio-desktop",
    "displayName": "draw.io Desktop",
    "publisher": "CN=...",
    "publisherDisplayName": "JGraph"
  }
}

This configuration generates Universal Windows Platform packages suitable for the Microsoft Store submission process.

Build Script Integration

The package.json references these configurations through distinct npm scripts:

{
  "scripts": {
    "release-win": "electron-builder --config electron-builder-win.json",
    "release-win32": "electron-builder --config electron-builder-win32.json",
    "release-win-arm64": "electron-builder --config electron-builder-win-arm64.json",
    "release-linux": "electron-builder --config electron-builder-linux-mac.json",
    "release-snap": "electron-builder --config electron-builder-snap.json",
    "release-appx": "electron-builder --config electron-builder-appx.json"
  }
}

When executing npm run release-win, electron-builder loads electron-builder-win.json, merges the platform-specific win and nsis sections with the common fields, and outputs installer files to the dist/ directory.

Summary

• drawio-desktop uses separate JSON files for each target platform to manage platform-specific build configurations cleanly
• Common fields like appId, productName, and directories are shared across all configuration files in the repository root
• Platform sections (win, mac, linux, snap, appx) define OS-specific packaging rules, signing requirements, and distribution formats
• The Windows family uses three distinct files (electron-builder-win.json, electron-builder-win32.json, electron-builder-win-arm64.json) to handle architecture differences
• macOS and Linux share a base configuration (electron-builder-linux-mac.json) but specify distinct targets through separate sections
• Specialized formats like Snap and AppX have dedicated configuration files that add store-specific metadata and confinement rules
• npm scripts in package.json invoke electron-builder with the --config flag to select the appropriate platform configuration

Frequently Asked Questions

How does electron-builder know which configuration file to use?

electron-builder accepts a --config command-line argument that specifies the JSON file path. The drawio-desktop repository defines separate npm scripts (e.g., release-win, release-linux) that each pass the corresponding platform-specific configuration file to electron-builder.

Can I modify the build output directory for a specific platform?

Yes. Each electron-builder-*.json file contains a directories.output field (typically set to "dist"). You can modify this value in any platform-specific configuration file to change where that platform's packages are generated, without affecting other builds.

What is the purpose of the extraResources field in these configuration files?

The extraResources array specifies files or directories that must be bundled alongside the application code but are not part of the main source tree. In drawio-desktop, this typically includes native binaries, icon sets, or runtime resources that need to be accessible to the packaged application after installation.

Why are there separate configuration files for different Windows architectures?

While the core packaging logic remains similar, electron-builder requires distinct arch specifications (x64, ia32, arm64) within the win.target configuration. Separate JSON files allow the drawio-desktop project to build for multiple Windows architectures in parallel without modifying configuration arrays during the build process, ensuring clean, maintainable build pipelines for each target platform.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}