hygull / nwjs-builder-phoenix

An npm package to package NW.js apps for all major platforms (Windows, Linux, MAC OS X).

nwjs-builder-phoenix

A possible solution to build and package a ready for distribution NW.js app for Windows, macOS and Linux.

Why Bother?

We already had nw-builder, but it has made little progress on the way, and nwjs-builder has been hard to continue due to personal and historic reasons.

electron-builder inspired me when I became an Electron user later, loose files excluding, various target formats, auto updater, artifacts publishing and code signing, amazing!

Although NW.js has much lesser popularity than Electron, and is really troubled by historic headaches, let's have something modern.

Features

• Building for Windows, macOS and Linux
  • Common: zip, 7z
  • Windows: nsis, nsis7z
  • macOS: TODO
  • Linux: TODO
• Building for different platforms concurrently
• Configurable executable fields and icons for Windows and macOS
• Exclusion of loose files from node_modules
• Chrome App support
• nwjs-ffmpeg-prebuilt integration
• Auto Updater
• TODO Rebuilding native modules
• TODO Code signing
• Ideas appreciated :)

Quick start

Let suppose, path to your app is D:\Users\Projects\NW\myapp (Windows) and /Users/Projects/NW/myapp (Linux/MAC OS X).

1. Open terminal ( CMD/BASH ).

2. Navigate to myapp directory using cd D:\Users\Projects\NW\myapp (Windows) | cd /Users/Projects/NW/myapp (Linux/MAC OS X).

3. Check package.json to have at least name, description, version, scripts fields. If you don't have package.json, please create it using npm init command (provide proper values as it asks) instead of creating it manually (as using npm init will add set most of the keys needed).

Here is the minimal one:

    {
      "name": "generator",
      "version": "1.0.0",
      "description": "An NW based desktop application",
      "scripts": {
        "test": "node ./test/test_any.js"
      }
    }

4. Now add build key and also update scripts.

    {
      "name": "generator",
      "version": "1.0.0",
      "description": "An NW based desktop application",
      "build": {
        "nwVersion": "0.35.1"
      },
      "scripts": {
        "test": "node ./test/test_any.js",
        "dist": "build --tasks win-x86,win-x64,linux-x86,linux-x64,mac-x64 --mirror https://dl.nwjs.io/ .",
        "start": "run --x86 --mirror https://dl.nwjs.io/ ."
      }
    }

5. Install nwjs-builder-phoenix locally using npm install nwjs-builder-phoenix --save-dev.

npm install nwjs-builder-phoenix --save-dev

6. Finally, run npm run dist.

npm run dist

That's it.

Note: Just wait for packaging process as it depends on speed of Network and number of selected target platforms.

Getting Started

• Make sure your NW.js project has a valid package.json (e.g. generated by npm init), and have basic fields like name, description and version filled.

• For apps destined for Mac, providing a product_string in the package.json will allow the Helper app to be renamed for you.

• Install nwjs-builder-phoenix as a devDependencies of your NW.js project as follows:

# Optional wine for building for Windows on other platforms.
# The command may differ in different Linux distributions.
#sudo apt-get install wine
npm install nwjs-builder-phoenix --save-dev

By installing it locally, build and run commands will be available in npm scripts. You can access option lists via ./node_modules/.bin/{ build, run } --help.

DO NOT install it globally, as the command names are just too common.

• Add build properties at the root of the package.json, for example:

// package.json
{
    "build": {
        "nwVersion": "0.14.7"
    }
}

This will specify the NW.js version we are using. See more in the following Options section.

• Add some helper npm scripts, for example:

// package.json
{
    "scripts": {
        // Deprecated. "dist": "build --win --mac --linux --x86 --x64 --mirror https://dl.nwjs.io/ .",
        "dist": "build --tasks win-x86,win-x64,linux-x86,linux-x64,mac-x64 --mirror https://dl.nwjs.io/ .",
        "start": "run --x86 --mirror https://dl.nwjs.io/ ."
    }
}

The above code snippet enables npm run dist and npm run start/npm start. The former builds for all major platforms and both x86 and x64 arch, and the latter runs the project with x86 binaries, both with the specified version of NW.js and use specified mirror to accelerate the download.

• Well done.

This should be the common use case, read the following Options section and FAQs if something is missing.

See also sample project and test cases for reference.

Options

Passing and managing commandline arguments can be painful. In nwjs-builder-phoenix, we configure via the build property of the package.json of your NW.js project.

Also see all available options here.

Differences to nwjs-builder

• nwjs-builder-phoenix queries versions.json only when a symbol like lts, stable or latest is used to specify a version.
• nwjs-builder-phoenix uses rcedit instead of node-resourcehacker, thus it's up to you to create proper .ico files with different sizes.
• nwjs-builder-phoenix supports node.js 4.x and later versions only.
• nwjs-builder-phoenix writes with TypeScript and benefits from strong typing and async/await functions.

Development

git clone https://github.com/evshiron/nwjs-builder-phoenix
cd nwjs-builder-phoenix
npm install

npm test

By the way, I use some custom strings in NSIS scripts which might not be fully translated, if anyone is interested in translating them into languages that aren't available, feel free to fork and send PRs.

Available Mirrors

If you have difficulties connecting to the official download source, you can specify a mirror via --mirror argument of both build and run, or by setting NWJS_MIRROR environment variable. Environment variables like HTTP_PROXY, HTTPS_PROXY and ALL_PROXY should be useful too.

• China Mainland
  • https://npm.taobao.org/mirrors/nwjs/
• Singapore
  • https://cnpmjs.org/mirrors/nwjs/

License

MIT