Skip to main content

​
Quick Start Guide

This guide will help you set up electron-builder in your Electron project and create your first build.

​
Prerequisites

Before you begin, make sure you have:
  • An Electron project initialized
  • electron-builder installed as a dev dependency (Installation Guide)

​
Setup Steps

1

Configure package.json metadata

Specify the standard fields in your application package.json. These fields are used for your app’s metadata:
package.json
{
  "name": "your-app-name",
  "version": "1.0.0",
  "description": "Your app description",
  "author": "Your Name <[email protected]>",
  "main": "main.js"
}
The name, description, version, and author fields are required for proper app packaging.
2

Add build configuration

Add the build configuration to your package.json:
package.json
{
  "build": {
    "appId": "com.your.app.id",
    "mac": {
      "category": "public.app-category.productivity"
    },
    "win": {
      "target": "nsis"
    },
    "linux": {
      "target": "AppImage"
    }
  }
}
You can also use separate configuration files (.js, .ts, .yml, .json, .json5). See configuration options for all available settings.

​
Alternative Configuration Files

Instead of package.json, you can create:
module.exports = {
  appId: "com.your.app.id",
  mac: {
    category: "public.app-category.productivity"
  },
  win: {
    target: "nsis"
  },
  linux: {
    target: "AppImage"
  }
}
3

Add application icons

Add icons for your application. electron-builder will automatically use the correct icon format for each platform.Create an build directory in your project root and add your icons:
build/
  ├── icon.icns          # macOS icon
  ├── icon.ico           # Windows icon
  └── icon.png           # Linux icon (at least 512x512)
electron-builder can generate all icon formats from a single 1024x1024 PNG file. Place it at build/icon.png and electron-builder will handle the conversions.
Learn more about icon requirements.
4

Add build scripts

Add build scripts to your package.json:
package.json
{
  "scripts": {
    "app:dir": "electron-builder --dir",
    "app:dist": "electron-builder",
    "postinstall": "electron-builder install-app-deps"
  }
}
Script descriptions:
  • app:dir - Generates the package directory without packaging it (useful for testing)
  • app:dist - Packages the app in a distributable format (DMG, installer, etc.)
  • postinstall - Ensures native dependencies match the Electron version
The postinstall script is recommended to ensure your native dependencies are always matched to the Electron version.
5

Build your application

Now you’re ready to build your application!
# Create distributable packages
npm run app:dist

# Or just generate the package directory (faster, for testing)
npm run app:dir
Your built application will be in the dist directory.

​
Important Notes

Everything is packaged into an asar archive by default. This is an Electron archive format that packages your app’s source code. You can disable this in the configuration if needed.

​
Native Dependencies

If you have native addons that are part of your application (not as a dependency), set nodeGypRebuild to true in your build configuration:
package.json
{
  "build": {
    "nodeGypRebuild": true
  }
}

​
Production Code Signing

For applications that will be shipped to production, you should sign your application. This is required for macOS and recommended for Windows.
Learn more about code signing and where to buy code signing certificates.

​
Example: Complete package.json

Here’s a complete example of a package.json configured for electron-builder:
package.json
{
  "name": "my-electron-app",
  "version": "1.0.0",
  "description": "My awesome Electron app",
  "author": "John Doe <[email protected]>",
  "main": "main.js",
  "scripts": {
    "start": "electron .",
    "app:dir": "electron-builder --dir",
    "app:dist": "electron-builder",
    "postinstall": "electron-builder install-app-deps"
  },
  "build": {
    "appId": "com.example.myapp",
    "mac": {
      "category": "public.app-category.productivity"
    },
    "win": {
      "target": "nsis"
    },
    "linux": {
      "target": ["AppImage", "deb"]
    }
  },
  "devDependencies": {
    "electron": "^latest",
    "electron-builder": "^latest"
  }
}

​
Using Boilerplates

electron-webpack-quick-start is a recommended way to create a new Electron application with electron-builder pre-configured.

​
Community Boilerplates

Consider using these community-maintained boilerplates:

​
Next Steps

Configuration

Explore all configuration options for advanced builds

Code Signing

Learn how to sign your application for distribution

Auto Update

Set up automatic updates for your application

Publishing

Publish your app to GitHub Releases, S3, and more

​
Debugging

If you encounter issues during the build process, enable debug logging: 
DEBUG=electron-builder npm run app:dist
Additional debug options:
  • FPM_DEBUG - More details about building Linux targets (except snap and AppImage)
  • DEBUG_DMG=true - More verbosity from hdiutil on macOS

Build docs developers (and LLMs) love

Get started for freeTalk to us