@kogs/nwjs

@kogs/nwjs

@kogs/nwjs is a command-line utility written in Node.js that streamlines the process of preparing a nw.js distribution.

This utility is intended for use in automated build pipelines or for development and testing purposes.

• Supports all platforms, architectures and versions.
• Supports both production and SDK builds.
• Caches builds to avoid unnecessary downloads.
• Minimal external dependencies: tar and JSZip.

Installation

npm install @kogs/nwjs -g

Usage

Usage: nwjs [options]

Options:
  --help                Show this help message and exit.
  --version             Show the version number and exit.
  --target-dir          Specify a target directory to install to.
  --version             Specify a version to install (e.g 0.49.2)
  --sdk                 Install the SDK flavor instead of the normal flavor.
  --no-cache            Disable caching of downloaded builds.
  --clear-cache         Clears the cache of downloaded builds.
  --platform <string>   Override the platform to install for.
  --arch <string>       Override the architecture to install for.
  --exclude <pattern>   Exclude files matching the given pattern.
  --download-server     Override the default download server to use.
  --locale <a,b,c..>    Define which locales to include in the build (defaults: all).
  --remove-pak-info     Remove .pak.info files to reduce the size of the build.

Documentation

• Versions - Specify a specific version of nw.js to install.
• Target Directory - Specify a target directory to install to.
• Platform / Architecture - Override the platform and architecture to install for.
• Caching - Cache downloaded builds to avoid unnecessary downloads.
• Development Build (SDK) - Install the SDK flavor instead of the normal flavor.
• Excluding Files - Exclude files from the build.
• Download Server - Override the default download server to use.
• Locales - Automatically remove locale files that you won't use.
• Remove .pak.info - Remove .pak.info files to reduce the size of the build.

Verions

Using the --version <version> option you can specify a specific version of nw.js to install. This should be a valid version number such as 0.49.2 or 0.48.0-beta1.

nwjs --version 0.48.0-beta1

If no version is specified, the latest stable version will be installed. This is determined by querying the directory listing of the download server.

nwjs # No version, latest is installed.

Target Directory

By default, nw.js will be installed in the current working directory. To specify your own target directory, use the --target-dir option.

nwjs --target-dir /path/to/target # Installs to /path/to/target.

Keep in mind that files will be overwritten if they already exist in the target directory.

Platform / Architecture

By default, the platform and architecture of the current system will be used. If you wish to override this, use the --platform and --arch options.

nwjs --platform win --arch x64 # Installs latest stable build for Windows x64.

Note: For compatibility with the Node.js API, the platform win32 is treated as win and the platform darwin is treated as osx.

At the time of writing, the following platforms and architectures are supported:

Platform	Architecture
win	x64 ia32
linux	x64 ia32
osx	x64

This utility does not validate against this table, and will attempt to download the build regardless of the platform or architecture specified. If the build does not exist, the download will fail.

Caching

By default, downloaded builds are cached to the operating system's temporary directory. Installing the same version multiple times will re-use the cached build, avoiding unnecessary downloads.

Path: os.tmpdir() + '/kogs-nwjs-cache/' + package

To disable this behavior, use the --no-cache option. The cache will not be checked or updated when this option is used.

nwjs --no-cache # Disables caching.

Additionally, the --clear-cache option can be used to clear the cache before a build starts. The cache will still be used unless --no-cache is also set.

nwjs --clear-cache # Clears the cache before installing.

Development Build (SDK)

By default, the normal flavor of nw.js will be installed. If you wish to install the SDK flavor instead, use the --sdk option.

nwjs --sdk # Installs latest stable SDK build.

Excluding Files

Providing the --exclude <pattern> option allows you to exclude files that match the pattern from the build. The pattern should be a valid regular expression.

nwjs --exclude "^credits.html$" # Excludes credits.html from the build.
nwjs --exclude "\.pak\.info$" # Excludes all .pak.info files from the build.

Notes on file exclusion:

• The pattern is matched against the file path as it appears inside the ZIP/TAR archive (minus the root directory), not the final file path on disk.
• To exclude .pak.info files more efficiently, see the Remove .pak.info section.
• To exclude locale files more efficiently, see the Locales section.

Download Server

By default, the utility will use the official download server when downloading builds. If you wish to use a different server, use the --download-server option.

nwjs --download-server https://example.com/

Notes on custom download servers:

• The server is expecting an Apache-style directory listing.
• Builds are scraped using /<a href="v([^"]+)\/">v[^<]+\/<\/a>/g
• Versions must match /^(\d+)\.(\d+)\.(\d+)(-[a-z0-9]+)?$/

Locale

By default, builds come with locale files for all languages supported by Chromium. According to the developer of nw.js, it is safe to remove locale files that you won't be using.

@kogs/nwjs makes this simple with the --locale <locales> option, where <locales> is a comma-separated list of locales to include.

You can find a list of locales supported by Chromium here.

nwjs --locale "sw,en-GB,en_US"

Notes on locale:

• You should use the locale IDs that Chromium uses, not platform-specific variations. For example, don't use en (OSX variation) for en-US, @kogs/nwjs will automatically adjust this when building for OSX.
• The locale files are not related to the language content of your application, it is related to the environment in which the application will be deployed. Do not exclude locale files unless you are 100% sure of the locale of the computers your application will be deployed onto.
• The use of hyphens and underscores differs between platforms, as such you can use either and @kogs/nwjs will automatically adjust them depending on the target platform (e.g en-gb == en_gb).
• Locale flags are case-insensitive (e.g en-GB == en-gb).

Remove .pak.info

During the Chromium build process for Windows and Linux builds, a .pak.info file is generated for each .pak file in /locales. Since 2018, CEF has been removing these files as part of their build script, but nw.js still includes them.

These files are not needed and can be safely removed. To help with this, @kogs/nwjs will automatically remove these if the --remove-pak-info option is used.

nwjs --remove-pak-info # Removes .pak.info files.

The --remove-pak-info is a more convinient and readable way of doing --exclude "^locales\/([^.]+)\.pak\.info|$" (see Excluding Files) and skips OSX builds as they do not include these files.

What is @kogs?

@kogs is a collection of packages that I've written to consolidate the code I often reuse across my projects with the following goals in mind:

• Consistent API.
• Minimal dependencies.
• Full TypeScript definitions.
• Avoid feature creep.
• ES6+ syntax.

All of the packages in the @kogs collection can be found on npm under the @kogs scope.

Contributing / Feedback / Issues

Feedback, bug reports and contributions are welcome. Please use the GitHub issue tracker and follow the guidelines found in the CONTRIBUTING file.

License

The code in this repository is licensed under the ISC license. See the LICENSE file for more information.