electron-maker-velopack

This is a maker for Electron Forge that uses velopack to build
distribution packages for an application.

For velopack docs, see https://docs.velopack.io .

For Electron Forge docs, see https://www.electronforge.io .

Status

This maker is in very early development. It works for my purposes
on Windows, but it is not thoroughly tested. Please consider it
a starting point.

Signing packages, in particular, is untested.

Supported platforms, prerequisites

The maker requires the command line tool vpk to be available on the path
and will fail with a corresponding error message otherwise.

Once you have a .NET SDK installed, you should be able to install the vpk
command line tool by running:

dotnet tool update -g vpk

Note that after the initial installation of the .NET SDK, you may have to
exit and re-enter your command interpreter sessions in order to make addition
of the .NET tools to your PATH variable effective.

The maker will try to run on any platform, but so far it has been tested only
on Windows.

Usage

First, install electron-maker-velopack as a development dependency for your package:

npm install --save-dev electron-maker-velopack

Then add some code of the following form to your forgeConfig.js file under makers:

makers:
// ...
{
name: 'electron-maker-velopack',
config: {
// ... see below for configuration options ...
},
},
// ...

The installer generated by velopack will run your application during the install
process in order to create shortcuts for the application, etc.. In order to handle
these setup tasks correctly, install the velopack package using

npm install velopack

in your application package and add the following code to the beginning of your
main.js entry point:

const { VelopackApp } = require('velopack');

VelopackApp.build().run();

For more details, see the [velopack documentation
and the velopack npm package.

Configuration

The maker takes its default configuration from the electron packager configuration
and the package.json data, in that order of precedence. You only need to add
specific maker configuration options if you want to override something or you need
an option that is not available in the packager configuration or package.json.

Options specified in the maker configuration will always take precedence over
derived defaults.

The maker configuration has the following declaration:

export type MakerVelopackConfig = {
allowInteraction?: boolean,
channel?: string,
delta?: string,
exclude?: string,
framework?: string[],
icon?: string,
noInstaller?: boolean,
noPortable?: boolean,
outputDir?: string,
packAuthors?: string,
packId?: string,
packTitle?: string,
packVersion?: string,
releaseNotes?: string,
runtime?: string,
shortcuts?: string[],
signParallel?: number,
signParams?: string,
signSkipDll?: boolean,
signTemplate?: string,
skipVeloAppCheck?: boolean,
splashImage?: string,
vpkExtraArguments?: string[],
vpkProgram?: string,
};

$3

If true, run vpk with stdio handles inherited from the parent process, in order to allow the user to interact with vpk.
(For example for confirming the overwriting of an existing release. If this is not given, vpk will automatically fail
in such cases.)

Enabling this has the downside that error reporting may be subpar because stdout/stderr output from vpk may be swallowed
by the Electron Forge build process in case of an error. If the vpk command fails without any visible error message,
try disabling this option.

$3

The release channel to pass to the --channel argument of vpk. (Otherwise, vpk uses its default channel.)

$3

The delta generation mode to pass to the --delta argument of vpk. This can be "BestSize", "BestSpeed", or "None".
(Otherwise, vpk defaults to the "BestSpeed" mode.)

Note that delta packages will only be generated if an explicit outputDir is given in the maker configuration
(see below) and this directory contains the previous package(s) to compute deltas against.

$3

A regex for excluding matching files from the package, to pass to the --exclude argument of vpk.
(vpk defaults to excluding .*\.pdb.)

$3

An array of strings to pass to the --framework argument of vpk, joined by commas. The strings specify the required runtimes to install during setup.

$3

The path to an icon file for the installer, to pass to the --icon argument of vpk.

This defaults to the icon specified in the packager configuration, if any.

$3

If true, do not build the executable installer. (--noInst argument to vpk.)

$3

If true, do not build the portable installer. (--noPortable argument to vpk.)

$3

The directory into which vpk should put the newly built packages, to pass to the --outputDir argument of vpk.

If this is not given, an empty directory will be created as velopack/${targetPlatform}/${targetArch}
under the Electron Forge out/make directory and passed to vpk as the --outputDir.
In this case, the delta configuration option has no effect since vpk will not find any previously built packages
in this directory.

If this option is specified, the given directory will not be cleared. Existing files will be kept in order to
allow pkg to built delta packages with respect to earlier versions.

$3

The authors string to pass to the --packAuthors argument of vpk. Defaults to author information pulled
from the package.json data.

$3

The package id string to pass to the --packId argument of vpk. This must be a valid nupkg ID (containing
only alphanumeric characters, underscores, dashes, and dots). Defaults to name in the packager configuration
or the app name, with characters not valid in nupkg IDs replaced by underscores.

This value is used for the of the generated nupkg.

$3

A human-friendly name of the applicaton to pass to the --packTitle argument of vpk. Defaults
to packagerConfig.name, or productName from package.json, or the app name.

This value is used for both the