Building for Windows

The top-level win configuration contains options for building Windows targets. These options apply to all Windows target types including NSIS, MSI, AppX, portable, and Squirrel.

Windows Targets Overview

NSIS

Default Windows installer with auto-updates

Portable

Standalone executable without installation

MSI

Windows Installer package format

Base Windows Configuration

The win key in your electron-builder configuration applies to all Windows targets:

{
  "build": {
    "win": {
      "target": ["nsis", "portable"],
      "icon": "build/icon.ico",
      "publisherName": "Your Company, Inc.",
      "signingHashAlgorithms": ["sha256"],
      "signDlls": true
    }
  }
}

For detailed Windows configuration options, see the WindowsConfiguration interface reference.

NSIS Installer

NSIS is the default and recommended target for Windows. It supports automatic updates, Unicode, and can build both 32-bit and 64-bit installers.

Basic NSIS Configuration

JSON
YAML

{
  "build": {
    "nsis": {
      "oneClick": true,
      "perMachine": false,
      "allowToChangeInstallationDirectory": false,
      "deleteAppDataOnUninstall": false,
      "createDesktopShortcut": true,
      "createStartMenuShortcut": true,
      "shortcutName": "My App"
    }
  }
}

build:
  nsis:
    oneClick: true
    perMachine: false
    allowToChangeInstallationDirectory: false
    deleteAppDataOnUninstall: false
    createDesktopShortcut: true
    createStartMenuShortcut: true
    shortcutName: My App

Assisted Installer (Non One-Click)

For more control over the installation process, use assisted installer mode:

JSON
YAML

{
  "build": {
    "nsis": {
      "oneClick": false,
      "allowToChangeInstallationDirectory": true,
      "allowElevation": true,
      "installerIcon": "build/installerIcon.ico",
      "uninstallerIcon": "build/uninstallerIcon.ico",
      "installerHeaderIcon": "build/installerHeaderIcon.ico"
    }
  }
}

build:
  nsis:
    oneClick: false
    allowToChangeInstallationDirectory: true
    allowElevation: true
    installerIcon: build/installerIcon.ico
    uninstallerIcon: build/uninstallerIcon.ico
    installerHeaderIcon: build/installerHeaderIcon.ico

Assisted installer allows users to choose between per-user and per-machine installation, and select the installation directory.

32-bit + 64-bit Support

Building for both architectures creates a single universal installer:

electron-builder --win --x64 --ia32

The installer automatically detects the system architecture and installs the appropriate version.

Web Installer

Web installer reduces download size by fetching the package files on-demand:

{
  "build": {
    "win": {
      "target": "nsis-web"
    },
    "nsisWeb": {
      "oneClick": true,
      "perMachine": false
    }
  }
}

Web installer automatically detects OS architecture and downloads the corresponding package. If download fails (antivirus, offline), users can download the package file manually and place it in the same directory as the installer.

Custom NSIS Script

Customize the NSIS installer by creating build/installer.nsh with custom macros:

!macro customHeader
  !system "echo '' > ${BUILD_RESOURCES_DIR}/customHeader"
!macroend

!macro preInit
  ; This macro is inserted at the beginning of the NSIS .OnInit callback
  !system "echo '' > ${BUILD_RESOURCES_DIR}/preInit"
!macroend

!macro customInit
  !system "echo '' > ${BUILD_RESOURCES_DIR}/customInit"
!macroend

!macro customInstall
  !system "echo '' > ${BUILD_RESOURCES_DIR}/customInstall"
!macroend

!macro customInstallMode
  # set $isForceMachineInstall or $isForceCurrentInstall
  # to enforce one or the other modes.
!macroend

!macro customWelcomePage
  # Welcome Page is not added by default for installer.
  !insertMacro MUI_PAGE_WELCOME
!macroend

!macro customUnWelcomePage
  !define MUI_WELCOMEPAGE_TITLE "custom title for uninstaller welcome page"
  !define MUI_WELCOMEPAGE_TEXT "custom text for uninstaller welcome page $\r$\n more"
  !insertmacro MUI_UNPAGE_WELCOME
!macroend

Available Custom Macros

customHeader - Add custom NSIS header content
preInit - Execute at the beginning of .OnInit callback
customInit - Custom initialization code
customUnInit - Custom uninstaller initialization
customInstall - Custom installation steps
customUnInstall - Custom uninstallation steps
customRemoveFiles - Custom file removal
customInstallMode - Force installation mode
customWelcomePage - Customize welcome page
customUnWelcomePage - Customize uninstaller welcome page
customUnInstallSection - Add custom uninstaller sections

Including Additional Resources

To include additional resources like scripts or MSI installers:

!macro customInstall
  File /oname=$PLUGINSDIR\extramsi.msi "${BUILD_RESOURCES_DIR}\extramsi.msi"
  ExecWait '"msiexec" /i "$PLUGINSDIR\extramsi.msi" /passive'
!macroend

Detect Update vs Fresh Install

${ifNot} ${isUpdated}
  # Code runs only on fresh install, not on update
${endIf}

Available variables: BUILD_RESOURCES_DIR, PROJECT_DIR, ONE_CLICK, and all other electron-builder flags. The build directory is added as addincludedir and build/x86-unicode, build/x86-ansi as addplugindir.

GUID vs Application Name

Windows uses registry keys for install/uninstall info. electron-builder automatically generates a name-based UUID v5 from your appId or name.

Do not change appId once your application is in use. The product name or description can be safely changed, but changing appId will cause issues with updates and uninstallation.

You can explicitly set a GUID using nsis.guid, but using appId is recommended:

{
  "build": {
    "appId": "com.company.app",
    "productName": "My Application"
  }
}

Set the Application User Model ID (AUMID) in your main process for proper Windows notifications:

app.setAppUserModelId(appId)

For complete NSIS configuration options, see the NsisOptions interface reference.

Portable App

Build a portable executable that doesn’t require installation:

electron-builder --win portable

Or in configuration:

{
  "build": {
    "win": {
      "target": "portable"
    }
  }
}

Portable Environment Variables

These environment variables are available in portable apps:

PORTABLE_EXECUTABLE_FILE - Path to the portable executable
PORTABLE_EXECUTABLE_DIR - Directory where the portable executable is located
PORTABLE_EXECUTABLE_APP_FILENAME - Sanitized app name for use in file paths

const appPath = process.env.PORTABLE_EXECUTABLE_DIR
const appFile = process.env.PORTABLE_EXECUTABLE_FILE
const appName = process.env.PORTABLE_EXECUTABLE_APP_FILENAME

Code Signing

Delegated Code Signing

Use a custom signing function for delegated code signing:

{
  "build": {
    "win": {
      "signtoolOptions": {
        "sign": "./customSign.js"
      }
    }
  }
}

Create customSign.js in your project root:

exports.default = async function(configuration) {
  // your custom code signing logic
  console.log('Signing:', configuration.path)
}

The sign function is called multiple times for different files. See why sign.js is called 8 times for details.

Custom Signature Verification

For NSIS updater with custom signature verification:

import { NsisUpdater } from "electron-updater"
import { verifySignatureByPublishName } from "win-verify-signature"

export default class AppUpdater {
  constructor() {
    const options = {
      requestHeaders: {
        // Any request headers to include here
      },
      provider: 'generic',
      url: 'https://example.com/auto-updates'
    }

    const autoUpdater = new NsisUpdater(options)
    autoUpdater.verifyUpdateCodeSignature = (publisherName, path) => {
      const result = verifySignatureByPublishName(path, publisherName)
      if (result.signed) return Promise.resolve(null)
      return Promise.resolve(result.message)
    }
    autoUpdater.addAuthHeader(`Bearer ${token}`)
    autoUpdater.checkForUpdatesAndNotify()
  }
}

Other Targets

electron-builder supports additional Windows targets:

MSI
AppX
Squirrel

Windows Installer package format:

{
  "build": {
    "win": {
      "target": "msi"
    }
  }
}

Universal Windows Platform package:

{
  "build": {
    "win": {
      "target": "appx"
    }
  }
}

Squirrel.Windows installer:

{
  "build": {
    "win": {
      "target": "squirrel"
    }
  }
}

Development Environment Setup

Parallels Windows 10 VM

For building AppX on macOS, Parallels VM is recommended:

Download VM

Open Parallels Desktop
File → New
Select “Modern.IE” in “Free Systems”
Select “Microsoft Edge on Windows 10”

Configure

Important: Disable “Share Mac user folders with Windows” feature. Do not run installers from shared folders.

Build

The VM will be automatically detected and used for AppX builds. It will start on-demand and suspend after the build.

No Windows 10 license required - free VMs are provided and expire after 90 days, but no additional setup is needed after expiration.

VirtualBox Windows 10 VM

Alternatively, use free VirtualBox:

Download

Visit Download virtual machines
Select “MSEdge on Win10 (x64) Stable”
Select “VirtualBox” platform
Download and follow installation instructions

VM password: Passw0rd!

VirtualBox is not automatically supported by electron-builder. You need to set up the build environment manually on Windows.

Building Multiple Targets

# Build specific targets
electron-builder --win nsis
electron-builder --win portable

# Build multiple targets
electron-builder --win nsis portable msi

# Build for multiple architectures
electron-builder --win --x64 --ia32

Get Started

Core Concepts

Packaging

Distribution

CLI

Windows Targets Overview

NSIS

Portable

MSI

Base Windows Configuration

NSIS Installer

Basic NSIS Configuration

Assisted Installer (Non One-Click)

32-bit + 64-bit Support

Web Installer

Custom NSIS Script

Available Custom Macros

Including Additional Resources

Detect Update vs Fresh Install

GUID vs Application Name

Portable App

Portable Environment Variables

Code Signing

Delegated Code Signing

Custom Signature Verification

Other Targets

Development Environment Setup

Parallels Windows 10 VM

VirtualBox Windows 10 VM

Building Multiple Targets

Build docs developers (and LLMs) love

Get Started

Core Concepts

Packaging

Distribution

CLI

​Windows Targets Overview

NSIS

Portable

MSI

​Base Windows Configuration

​NSIS Installer

​Basic NSIS Configuration

​Assisted Installer (Non One-Click)

​32-bit + 64-bit Support

​Web Installer

​Custom NSIS Script

​Available Custom Macros

​Including Additional Resources

​Detect Update vs Fresh Install

​GUID vs Application Name

​Portable App

​Portable Environment Variables

​Code Signing

​Delegated Code Signing

​Custom Signature Verification

​Other Targets

​Development Environment Setup

​Parallels Windows 10 VM

​VirtualBox Windows 10 VM

​Building Multiple Targets

Build docs developers (and LLMs) love

Windows Targets Overview

Base Windows Configuration

NSIS Installer

Basic NSIS Configuration

Assisted Installer (Non One-Click)

32-bit + 64-bit Support

Web Installer

Custom NSIS Script

Available Custom Macros

Including Additional Resources

Detect Update vs Fresh Install

GUID vs Application Name

Portable App

Portable Environment Variables

Code Signing

Delegated Code Signing

Custom Signature Verification

Other Targets

Development Environment Setup

Parallels Windows 10 VM

VirtualBox Windows 10 VM

Building Multiple Targets