WIX-MSI

Package node.js application to a standalone executable and pack it into a msi installer (Windows only).

This module will:

• Create a standalone binary that does not require node,
• Pack it into a Windows msi installer that:
  • Extract info from package.json such as bin name, provider's name, and so on,
  • Automatically create a license panel in installer from LICENSE/LICENSE.md file, if any,
  • Automatically create in the windows start menu an entry that contains link to the homepage URL filled in package.json or provided in cli,
  • Automatically update the PATH environmement variable with the install folder.
• Allow to customize the installer and others as executable name, etc.,
• Next to the previous point, a validation of the user's input is performed to ensure their consistency.

Note it does not require any third-software pre-installed (binaries of the installer, i.e. wixtoolset, will be locally downloaded in the package installation folder from its official repository).

Table of Contents

• Install
• Use
• Customize Installer and Installation
  • Important Settings
    • UUID
    • Executable name
  • Installer UI
  • Windows Applications Menu and Panel
• Options
• Rc file
• Mapping Project Sources
• Known Limitations
• Versioning
• Credits
• License

Install

As this module introduces constraints to both target os and arch (respectively win32 and x64), install it globally, as an optional dependency or launch it using npx to avoid to constrain your module with these settings.

npm i wix-msi -g

Use

wix-msi target_bin

where target_bin is a bin entry of the package.json

Customize Installer and Installation

Important Settings

UUID

The Product unique identifier assigned to this installer/application. It could be set using the -U/--uuid flag.

Note once assigned, it should note be changed in order to be able to perform update.

If not provided, it will be automatically generated and serialized in a file named .wixrc.

Executable name

Executable of the node application is set by default with the target bin entry of the package.json.

It could be changed using the -e/--exe flag to any name.

Installer UI

The screenshots above show the UI with default settings.

Customization of the installer UI could be performed using the following options:

• Left part of the introduction panel:
  • The -B/--background flag allows to customize this part with a png/jpg image,
  • Image will be automatically resized to fit the expected size of {493x176}.
• Top Banner of panels:
  • -b/--banner flag allows to put an image (png/jpg) on the right part of the banner of panels (expected the intro one),
  • This place is for a {90x48} image,
  • Image will be automatically resized to fit the expected place trying to keep user's image ratio at best.
• Background color:
  • Using -c/--color flag with a css-like color (i.e. either named or hexadecimal one) allows to customize (part of) the background color of panels.
• License panel:
  • Automatically added to the installer if a LICENSE/LICENSE.MD file is found,
  • Adding --no-l/--no-license flag allows to not include it.

Windows Applications Menu and Panel

The screenshots above show the installation result in both application menu and application panel.

Customization of the installation could be performed using the following options:

Windows Application Menu

• Shorcut Link:
  • Using the -H/--homepage allows to change URL of the link sortcut added to the directory of the windows menu for this application.
  • Default value use the homepage set in package json, if any,
  • If not, no shortcut link is created.

Windows Application Panel

• Icon of application:
  • Using the -i/--icon allows to modify the icon used for the Windows application panel.
  • Icon should be a png/ico image,
  • Image will be automatically resized to fit the expected size of {256x256}.

Options

option	desc	value	default
-d / --dir	build folder	path(*)	./build
-U / --uuid	product unique identifier	uuid	automatically generated if not provided (and saved in wixrc file)
-e / --exe	modify the executable name	string	package.bin[target_bin]
-f / --files	use the 'files' entry of package.json to get sources (see here)	boolean	false
-l / --license	include license panel in msi installer (Done if a LICENSE or LICENSE.md file is found)	boolean	true
-H / --homepage	URL of the shortcut added to menu directory (not added if undefined)	URL	package.homepage
-a / --author	provider of the package	string	package.author
-i / --icon	icon displayed in Windows application panel (.ico or png file). Note png file will be automatically resized to a 256x256 image	path(*)	assets/icon.png from this module
-b / --banner	image used on the right of the top banner of installer panels (a 90x48 png/jpg image). Note it will be automatically resized to expected size keeping its ratio as best	path(*)	assets/banner.png from this module
-B / --background	left image displayed in the introduction panel (a 493x176 png/jpg image). Note it will be automatically resized to expected size	path(*)	assets/background.png from this module
-c / --color	background color of panels	css color	'white'
-s / --save	save settings in .wixrc file	boolean	n.a.

(*) path must be relative from the execution directory.

Rc file

A .wixrc file could be use to store options:

{
  "target-bin": {
    "uuid": "12345678-90ab-cdef-1234-567890abcde",
    "icon": "./myIcon.png"
  }
}

Using the -s/--save option will generated it if the validation of user's settings succeed.

Mapping Project Sources

Packaging the application in a standalone executable is done via the pkg module.

By default, mapping of the required files/deps is done via the 'bin' property of the package.json and then found via the calls done to 'require' but:

• it does not deal with non-literal argument aka call of type:

    const m = require(variable) // Not supported

• Use of ESM is not supported (yet) aka call of 'import'

    import a from 'a' // Not supported

For such case, the -f/--files option has been introduced in order to use the 'files' property of the package.json to perform this task. Note, in this case, all files matching with the glob patterns of this property will be included and not only the required ones as for default case.

Known Limitations

• The 'bin' property of the package.json must not be provided as a string, but as an object,
• The mapping of the sources to pack is done for CommonJS modules (ESM is not supported by default.) See here how to bypass this limitation,
• Package version should strictly follow the x.y.z format where x,y and z are integers (it does not work with beta/rc or other usual suffix used for package version). If not, the validation step will raise and error and stop the packaging,
• Note it does not deal with signing the produced installer i.e. installing the msi on other computer could araise the "Windows Defender Smartscreen" about unrecognized app. Have a look (here) about the need of EV certificates for such purposes.

Versioning

While it's still in beta, version will follow v0.Y.Z format, where:

• Y: Major (could imply breaking changes),
• Z: Minor or patch.

Credits

• Nicolas Barriquand (nbarikipoulos)

License

This module is MIT licensed. See LICENSE.