electron-userland
electron-builder 
A complete solution to package and build a ready for distribution Electron, Proton Native app for macOS, Windows and Linux with “auto update” support out of the box. :shipit:
Always looking for community contributions! 👀 Setting up a dev environment is easy to do 🪩
Sponsors
Documentation
See the full documentation on electron.build.
- NPM packages management:
- Native application dependencies compilation (including Yarn support).
- Development dependencies are never included. You don't need to ignore them explicitly.
- Two package.json structure is supported, but you are not forced to use it even if you have native production dependencies.
- Code Signing on a CI server or development machine.
- Auto Update ready application packaging.
- Numerous target formats:
- All platforms:
7z,zip,tar.xz,tar.7z,tar.lz,tar.gz,tar.bz2,dir(unpacked directory). - macOS:
dmg,pkg,mas. - Linux: AppImage, snap, debian package (
deb),rpm,freebsd,pacman,p5p,apk. - Windows:
nsis(Installer),nsis-web(Web installer),portable(portable app without installation), AppX (Windows Store), MSI, Squirrel.Windows.
- All platforms:
- Publishing artifacts to GitHub Releases, Amazon S3, DigitalOcean Spaces and Bintray.
- Advanced building:
- Pack in a distributable format already packaged app.
- Separate build steps.
- Build and publish in parallel, using hard links on CI server to reduce IO and disk space usage.
- electron-compile support (compile for release-time on the fly on build).
- Docker images to build Electron app for Linux or Windows on any platform.
- Proton Native support.
- Downloads all required tools files on demand automatically (e.g. to code sign windows application, to make AppX), no need to setup.
| Question | Answer |
|---|---|
| “I want to configure electron-builder” | See options |
| “I found a bug or I have a question” | Open an issue |
| “I want to support development” | Donate |
Installation
Yarn is strongly recommended instead of npm.
yarn add electron-builder --dev
Note for Yarn 3
Yarn 3 use PnP by default, but electron-builder still need node-modules(ref: yarnpkg/berry#4804). Add configuration in the .yarnrc.yaml as follows:
nodeLinker: "node-modules"will declare to use node-modules instead of PnP.
Quick Setup Guide
electron-webpack-quick-start is a recommended way to create a new Electron application. See Boilerplates.
Specify the standard fields in the application
package.json— name,description,versionand author.Specify the build configuration in the
package.jsonas follows:"build": { "appId": "your.id", "mac": { "category": "your.app.category.type" } }See all options. Option files to indicate which files should be packed in the final application, including the entry file, maybe required. You can also use separate configuration files, such as
js,ts,yml, andjson/json5. See read-config-file for supported extensions. JS Example for programmatic APIAdd icons.
Add the scripts key to the development
package.json:"scripts": { "app:dir": "electron-builder --dir", "app:dist": "electron-builder" }Then you can run
yarn app:dist(to package in a distributable format (e.g. dmg, windows installer, deb package)) oryarn app:dir(only generates the package directory without really packaging it. This is useful for testing purposes).To ensure your native dependencies are always matched electron version, simply add script
"postinstall": "electron-builder install-app-deps"to yourpackage.json.If you have native addons of your own that are part of the application (not as a dependency), set nodeGypRebuild to
true.
Please note that everything is packaged into an asar archive by default.
For an app that will be shipped to production, you should sign your application. See Where to buy code signing certificates.
Programmatic Usage
See node_modules/electron-builder/out/index.d.ts. Typings for TypeScript are provided and also can be found here.
Code snippet provided below is also shown "in action" here as well.
"use strict"
const builder = require("electron-builder")
const Platform = builder.Platform
// Promise is returned
builder.build({
targets: Platform.MAC.createTarget(),
config: {
"//": "build options, see https://goo.gl/QQXmcV"
}
})
.then(() => {
// handle result
})
.catch((error) => {
// handle error
})Boilerplates
- electron-webpack-quick-start — A bare minimum project structure to get started developing with electron-webpack. Recommended.
- electron-react-boilerplate A boilerplate for scalable cross-platform desktop apps.
- electron-react-redux-boilerplate A minimal boilerplate to get started with Electron, React and Redux.
- electron-boilerplate A minimalistic yet comprehensive boilerplate application.
- Vue CLI 3 plugin for Electron A Vue CLI 3 plugin for Electron with no required configuration.
- electron-vue-vite A real simple Electron + Vue3 + Vite5 boilerplate.
- vite-electron-builder Secure boilerplate for Electron app based on Vite. Supports multiple frameworks.
- electronjs-with-nextjs ElectronJS application with NextJS and TypeScript.
Debug
Set the DEBUG environment variable to debug what electron-builder is doing:
DEBUG=electron-builderFPM_DEBUG env to add more details about building linux targets (except snap and appimage).
DEBUG_DMG=true env var to add more debugging/verbosity from hdiutil (macOS).
!!! tip "cmd" On Windows the environment variable is set using the set command.
```bash
set DEBUG=electron-builder
```!!! tip "PowerShell" PowerShell uses different syntax to set environment variables.
```bash
$env:DEBUG=electron-builder
```Donate
We do this open source work in our free time. If you'd like us to invest more time on it, please donate.