Customising and Branding the MSI installer Doesn't work or requires better documentation

Electron-Builder Version: v24.13.3
Node Version: v20.12.2
Electron Version:
v30.0.1
Electron Type (current, beta, nightly):

Target: Win x64 MSI
Unlike the NSIS target there doesn't appear to be an easy way to customise or brand the MSI installer. The NSIS configuration provides the following properties; installerSidebar and installerHeader to customise the visual aspects of the installer and include to add custom actions via macros. From the Wix documentation it should be possible to customise the installer UI by passing the following arguments to the Light executable -dWixUIBannerBmp=<SomeBitmapFile 493 x 58>.bmp for the top banner and -dWixUIDialogBmp=<SomeBitmapFile 493 x 312>.bmp In addition Light will need to know which directory to search for these two files and its suggested that this can be provided with the argument -b <Path>.

The electron-builder MSI Configuration documentation states that there is the property additionalLightArgs for just this purpose. However, if you attempt to use this property you get the following error:

> electron-builder

  • electron-builder  version=24.13.3 os=10.0.19045
  • loaded configuration  file=package.json ("build" field)
  ⨯ Invalid configuration object. electron-builder 24.13.3 has been initialized using a configuration object that does not match the API schema.
 - configuration.msi has an unknown property 'additionalLightArgs'. These properties are valid:
   object { additionalWixArgs?, artifactName?, createDesktopShortcut?, createStartMenuShortcut?, menuCategory?, oneClick?, perMachine?, publish?, runAfterFinish?, shortcutName?, upgradeCode?, warningsAsErrors? }    
     How to fix:
     1. Open https://www.electron.build/configuration/configuration
     2. Search the option name on the page (or type in into Search to find across the docs).
       * Not found? The option was deprecated or not exists (check spelling).
       * Found? Check that the option in the appropriate place. e.g. "title" only in the "dmg", not in the root.
  failedTask=build stackTrace=ValidationError: Invalid configuration object. electron-builder 24.13.3 has been initialized using a configuration object that does not match the API schema.
 - configuration.msi has an unknown property 'additionalLightArgs'. These properties are valid:
   object { additionalWixArgs?, artifactName?, createDesktopShortcut?, createStartMenuShortcut?, menuCategory?, oneClick?, perMachine?, publish?, runAfterFinish?, shortcutName?, upgradeCode?, warningsAsErrors? }    
     How to fix:
     1. Open https://www.electron.build/configuration/configuration
     2. Search the option name on the page (or type in into Search to find across the docs).
       * Not found? The option was deprecated or not exists (check spelling).
       * Found? Check that the option in the appropriate place. e.g. "title" only in the "dmg", not in the root.

The property additionalLightArgs is unknown. The documentation needs updating?

That leaves the other Wix related configuration property additionalWixArgs If you pass the same 3 values ("-dWixUIBannerBmp=<SomeBitmapFile 493 x 58>.bmp", "-dWixUIDialogBmp=<SomeBitmapFile 493 x 312>.bmp", "-b <Path>") to additionalWixArgs then with the "-b <Path>" value the build fails with an error that "-b <Path>" is not a valid argument for Candle.exe, If you remove "-b <Path>" from the list of values then you get an error

  • building        target=MSI arch=x64 file=release\<Project Name> 3.30.0.msi
  ⨯ Exit code: 103. Command failed: C:\Users\<UserName>\AppData\Local\electron-builder\Cache\wix\wix-4.0.0.5512.2\light.exe -out C:\<Project Folder>\release\<Project Name> 3.30.0.msi -v -spdb -sw1076 -dappDir=C:\<Project Folder>\release\win-unpacked -pedantic -wx -dWixUIBannerBmp=MSITopBanner.bmp -dWixUIDialogBmp=MSIBackground.bmp -ext WixUIExtension project.wixobj
C:\agent\_work\9\s\src\ext\UIExtension\wixlib\Common.wxs(7) : error LGHT0103 : The system cannot find the file 'MSITopBanner.bmp'.

WiX Toolset Linker version 4.0.0.5512
Copyright (c) .NET Foundation and contributors. All rights reserved.

C:\agent\_work\9\s\src\ext\UIExtension\wixlib\Common.wxs(7) : error LGHT0103 : The system cannot find the file 'MSITopBanner.bmp'.
  failedTask=build stackTrace=Error: Exit code: 103. Command failed: C:\Users\<UserName>\AppData\Local\electron-builder\Cache\wix\wix-4.0.0.5512.2\light.exe -out C:\<Project Folder>\release\<Project Name> 3.30.0.msi -v -spdb -sw1076 -dappDir=C:\<Project Folder>\release\win-unpacked -pedantic -wx -dWixUIBannerBmp=MSITopBanner.bmp -dWixUIDialogBmp=MSIBackground.bmp -ext WixUIExtension project.wixobj
C:\agent\_work\9\s\src\ext\UIExtension\wixlib\Common.wxs(7) : error LGHT0103 : The system cannot find the file 'MSITopBanner.bmp'.

WiX Toolset Linker version 4.0.0.5512
Copyright (c) .NET Foundation and contributors. All rights reserved.

C:\agent\_work\9\s\src\ext\UIExtension\wixlib\Common.wxs(7) : error LGHT0103 : The system cannot find the file 'MSITopBanner.bmp'.

    at C:\<Project Folder>\node_modules\builder-util\src\util.ts:135:18
    at ChildProcess.exithandler (node:child_process:430:5)
    at ChildProcess.emit (node:events:518:28)
    at maybeClose (node:internal/child_process:1105:16)
    at Process.ChildProcess._handle.onexit (node:internal/child_process:305:5)

Light seems to understand the args but can't find the files.

If you pass absolute file paths then the build just freezes - the process has to be terminated. If you pass relative paths such as you can with NSIS then again you get file not found errors.

A minimum requirement would just be some up-to-date documentation that explains how to make this work with the existing configuration properties to achieve the same results as we can for NSIS targets.

Ideally it would more convenient if the MSI configuration had the same respective properties as the NSIS configuration in terms of equivalent poperties to installerSidebar and installerHeader and the mechanics of passing the values was handled by the code as it is with the NSIS target.

electron-userland / electron-builder

Customising and Branding the MSI installer Doesn't work or requires better documentation #8189