search

electron-userland / electron-wix-msi

:dvd: Create traditional MSI installers for your Electron app
MIT License
315 stars 91 forks source link
electron electronjs installer msi wix wix-toolset

readme

electron-wix-msi

Build status Coverage Status TypeScript

Traditional MSI Installers

Most Electron developers use the official windows-installer to create Windows installers. It does not require Administrator privileges and comes bundled with an automatic updater. If your app targets consumers, it will likely be the better choice.

However, if you need to create a traditional MSI the way Microsoft intended for software to be installed, this module is your friend. It creates a standalone MSI that installs your application to Program Files or any user-defined directory, much like the installers for Office, Node.js, or other popular apps. It allows up- and downgrades. For more details, see: Should I use this?

Look & Feel

Installer GIF

Prerequisites

Before using this module, make sure to install the Wix toolkit v3. Only the command line tools are required. If you are using AppVeyor or another Windows CI system, it is likely already installed.

npm i --save-dev electron-wix-msi

Whats new?

Version 3 is a major release for this toolkit. Many internals were reworked and V3 delivers improvements listed below. Please look out for the **🆕 icon throughout this documentation for new parameter. Versions 4 and above are only adding features and requiring newer versions of Node.js without actually requiring any code changes on your part.

See the CHANGELOG.md for details.

New install folder structure

A new folder structure allows to update the MSI installation while your app is running without temporarily corrupting the installation. If files are locked during an update then the MSI engine schedules file operation after the next reboot. While files that are not locked will be overwritten immediately. That can cause unexpected behavior of your app. The version-based folder structure avoids these problems and leads to a more robust user experience.

C:\Program Files\
└─ Kittens
     └─ app-x.x.x // version of the MSI
     └─ .installInfo // contains information about the installation
     └─ kittens.exe // stub executable that launches the newest version
     └─ Update.exe // optional auto updater

Auto launch feature

Auto updating was a long missing feature for MSIs. No more!. The integration of special Squirrel.Windows version allows us to enable auto-updating. This feature is optional and can be enabled/disabled at package time, install time and can even be controlled at run time of your App. See end user documentation

Auto update feature

Auto updating was a long missing feature for MSIs. No more! The integration of a special Squirrel.Windows version allows us to enable auto-updating. This feature is completely optional and can be enabled/disabled at package time, install time and can even be controlled at run time of your App.

Desktop shortcut

Your App will now also have a shortcut on the Desktop.

Usage

Creating an installer is a three-step process:

import { MSICreator } from 'electron-wix-msi';

// Step 1: Instantiate the MSICreator
const msiCreator = new MSICreator({
  appDirectory: '/path/to/built/app',
  description: 'My amazing Kitten simulator',
  exe: 'kittens',
  name: 'Kittens',
  manufacturer: 'Kitten Technologies',
  version: '1.1.2',
  outputDirectory: '/path/to/output/folder'
});

// Step 2: Create a .wxs template file
const supportBinaries = await msiCreator.create();

// 🆕 Step 2a: optionally sign support binaries if you
// sign you binaries as part of of your packaging script
supportBinaries.forEach(async (binary) => {
  // Binaries are the new stub executable and optionally
  // the Squirrel auto updater.
  await signFile(binary);
});

// Step 3: Compile the template to a .msi file
await msiCreator.compile();

Configuration

UI Configuration (Optional)

The ui property in the options passed to the installer instance allows more detailed configuration of the UI. It has the following optional properties:

Template Configuration (Optional)

This module uses XML bulding blocks to generate the final .wxs file. After instantiating the class, but before calling create(), you can change the default XML. The available fields on the class are:

🆕 End user documentation

License

MIT, please see LICENSE.md for details.