{"id":13111,"library":"electron-builder","title":"Electron Builder","description":"Electron Builder is a comprehensive, open-source solution for packaging and building cross-platform Electron applications, supporting macOS, Windows, and Linux from a single configuration. The current stable version is 26.8.1, with frequent patch and minor releases addressing bug fixes, security updates (like those for `tar` dependency), and feature enhancements. Major versions, which may introduce breaking changes or significant architectural shifts, are typically released periodically, often aligning with new Electron versions. Its key differentiators include out-of-the-box auto-update capabilities via `electron-updater`, extensive configuration options for various installers (e.g., NSIS, DMG, AppImage, Flatpak), and streamlined processes for code signing and notarization, making it an essential tool for deploying professional Electron desktop applications.","status":"active","version":"26.8.1","language":"javascript","source_language":"en","source_url":"https://github.com/electron-userland/electron-builder","tags":["javascript","electron","builder","build","installer","install","packager","pack","nsis","typescript"],"install":[{"cmd":"npm install electron-builder","lang":"bash","label":"npm"},{"cmd":"yarn add electron-builder","lang":"bash","label":"yarn"},{"cmd":"pnpm add electron-builder","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The primary programmatic API for initiating a build. Electron Builder uses ES Modules internally and provides TypeScript types.","wrong":"const build = require('electron-builder').build","symbol":"build","correct":"import { build } from 'electron-builder'"},{"note":"Type import for `electron-builder`'s configuration object, useful for `package.json` `build` key or external config files for type-checking and autocompletion in TypeScript projects.","symbol":"Configuration","correct":"import type { Configuration } from 'electron-builder'"},{"note":"Used to specify target platforms (e.g., `Platform.MAC`, `Platform.WINDOWS`) when calling the `build` function programmatically.","wrong":"import { Target } from 'electron-builder'","symbol":"Platform","correct":"import { Platform } from 'electron-builder'"}],"quickstart":{"code":"import { build, Platform } from 'electron-builder';\nimport path from 'path';\n\n// Basic programmatic build configuration for an Electron application\n// This example builds for macOS, Windows, and Linux with default targets.\nasync function buildApp() {\n  try {\n    const results = await build({\n      projectDir: path.resolve(__dirname, '..'), // Assumes this script is in a 'scripts' dir\n      targets: Platform.current().createTarget(), // Builds for the current OS\n      config: {\n        appId: 'com.example.myapp',\n        productName: 'My Awesome App',\n        directories: {\n          output: 'dist/artifacts',\n          buildResources: 'build-resources'\n        },\n        files: [\n          'package.json',\n          '**/*'\n        ],\n        extraFiles: [\n          // Example: Include a custom config file from project root\n          { from: 'config.json', to: '.' }\n        ],\n        mac: {\n          category: 'public.app-category.developer-tools',\n          target: ['dmg', 'zip'],\n          notarize: {\n            teamId: process.env.APPLE_TEAM_ID ?? '',\n          }\n        },\n        win: {\n          target: ['nsis', 'zip']\n        },\n        linux: {\n          target: ['AppImage', 'deb']\n        }\n      }\n    });\n    console.log('Build successful:', results);\n  } catch (error) {\n    console.error('Build failed:', error);\n    process.exit(1);\n  }\n}\n\nbuildApp();","lang":"typescript","description":"This quickstart demonstrates how to programmatically build an Electron application for multiple platforms (macOS, Windows, Linux) using `electron-builder`'s TypeScript API."},"warnings":[{"fix":"Upgrade your Node.js runtime to version 18 or higher. If using nvm, run `nvm install 18 && nvm use 18`. Update `engines.node` in `package.json` to reflect this requirement.","message":"Electron Builder v26.0.0 and later requires Node.js >=18.0.0. Previous versions might have supported Node.js 14 or 16. Ensure your development environment and CI/CD pipelines use a compatible Node.js version.","severity":"breaking","affected_versions":">=26.0.0"},{"fix":"Ensure `APPLE_ID`, `APPLE_ID_PASS`, and `APPLE_TEAM_ID` environment variables are correctly set. Configure the `notarize` option in your `mac` build configuration. Refer to the official `electron-builder` documentation on code signing and notarization for the latest requirements.","message":"macOS Notarization and Code Signing: Building for macOS requires careful handling of code signing and notarization for distribution outside the Mac App Store. Incorrect setup often leads to build failures or apps that cannot be launched.","severity":"gotcha","affected_versions":">=22.0.0"},{"fix":"Periodically update `electron-builder` to its latest patch or minor version using `npm update electron-builder` or `yarn upgrade electron-builder`. Monitor `electron-builder`'s release notes for security advisories.","message":"Regular updates to core dependencies like `tar` are common for security patches. Failing to update `electron-builder` can expose your build process or resulting application to known vulnerabilities.","severity":"security","affected_versions":">=22.0.0"},{"fix":"For complex or problematic cross-platform builds, consider using dedicated CI/CD pipelines with runners on the target operating systems (e.g., Windows VMs for Windows builds). Ensure that `node_modules` are reinstalled on the target platform to avoid issues with native modules.","message":"Cross-platform build issues, particularly building Windows installers on macOS or Linux, can arise due to platform-specific dependencies, file system differences (e.g., symbolic links, permissions), or binary incompatibilities. While `electron-builder` supports cross-compilation, direct builds on the target OS are often more reliable for complex setups.","severity":"gotcha","affected_versions":">=20.0.0"},{"fix":"Add `\"postinstall\": \"electron-builder install-app-deps\"` to your `package.json` scripts. This command ensures native modules are correctly compiled for your Electron target. Alternatively, use the `nodeGypRebuild: true` option in your build configuration.","message":"Native Node.js modules (C/C++ addons) must be rebuilt against the specific Electron version and architecture used in your build. Incorrectly handled native modules can lead to runtime errors in the packaged application.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Check your internet connection. Try clearing the `electron-builder` cache by deleting `~/.cache/electron` or setting `ELECTRON_BUILDER_CACHE` to a different path and re-running the build. Verify your `electronVersion` in the config.","cause":"Electron itself or its dependencies for the target platform could not be downloaded or located, often due to network issues, corrupted cache, or incorrect configuration.","error":"Error: Electron distribution for 'mac' is not found (os: mac, arch: x64)"},{"fix":"Ensure `electron-builder` is installed correctly. Try deleting `node_modules` and `package-lock.json` (or `yarn.lock`), then reinstalling dependencies with `npm install` or `yarn install`. For specific issues on Windows or with Node.js version managers, ensure PATH is correctly configured for the package manager's executables.","cause":"This error typically indicates that the `app-builder` native dependency, which `electron-builder` relies on for various build tasks, could not be installed or found. This can be caused by platform incompatibilities or npm/yarn issues.","error":"Error: Cannot find module 'app-builder-bin'"},{"fix":"Verify your Apple Developer ID certificate is installed and valid. Check your `mac` build configuration for `identity`, `hardenedRuntime`, and `entitlements` settings. Ensure the `APPLE_TEAM_ID` is correctly configured for notarization.","cause":"Indicates a problem during the macOS code signing process, often due to invalid certificates, incorrect entitlements, or missing provisioning profiles.","error":"Error: Command failed with exit code 1: ... codesign"},{"fix":"Ensure all modules required at runtime are in `dependencies`. Move build-time only modules to `devDependencies`. If a module is truly optional or only for specific environments, consider adding it to `build.externals` or setting `ELECTRON_BUILDER_ALLOW_UNRESOLVED_DEPENDENCIES=true` (use with caution).","cause":"`electron-builder` tries to resolve all `dependencies` (not `devDependencies`) within your Electron app. If it finds modules listed as `dependencies` that cannot be resolved or are not meant for the production build, it will error.","error":"Error: Unresolved node modules: [module-name]"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"electron-builder"}