-
Notifications
You must be signed in to change notification settings - Fork 3.9k
How to package and distribute your apps
NOTE: some content in this wiki applies only to 0.12 and earlier versions. For official documentation on 0.13 and later, see http://docs.nwjs.io
Just put the files along with NW files in the same directory and then ship them to your users.
nw.exe and package.json should be in the same directory.
On OSX it's different: put the tree of your app in a directory named nwjs.app/Contents/Resources/app.nw
.
For more info and other ways of packaging, please read on.
The following sub-directories can be put in application's root directory:
- node_modules - any Node modules you want to deploy with your application
- plugins - NPAPI plugin files
You don't need to ship the nwsnapshot
file in the downloaded zip.
Caution: do not assume your node_modules
that target one platform work as is in all platforms. For instance node-email-templates
has specific Windows & Mac os x npm install
commands. Besides, it requires python to install properly, which is not installed by default on Windows.
As a rule of thumb npm install
your package.json
on each platform you target to ensure everything works as expected.
Since our package system is similar to LÖVE, following guides are modified from its Wiki.
An app's package is a zip archive with .nw
as extension. Three caveats:
- There must be a
package.json
file that describes the package, see Manifest format. - The
package.json
file must be at the root of the archive. - In the
.nw
, the file and directory path names are case sensitive. This can be puzzling for Windows and Mac OS X users, whose filesystem is case insensitive, and whose apps may work when unzipped but not when packaged.
Here's how to proceed to generate a working .nw
file:
- Create a zip file (this is built into XP, Vista and 7)
- Copy all of your files into the zip file, retaining directory structure and making sure that the
package.json
file is in the root directory (if you make a zip file containing a folder with your stuff in it, then it's not going to work) - Rename the file extension from
.zip
to.nw
. By default, file extensions may be hidden. You need to (pressalt
), go to folder options and uncheck "Hide extensions for known file types" to be able to rename the zip.
From the command line:
- Go to your project directory a la
cd ~/Projects/my_app
- Run
zip -r ../${PWD##*/}.nw *
- Your fully-prepared
.nw
file shall be located right outside of your project directory - Cake!
- You can zip your files and name it
package.nw
and place it in the same directory with nw executable. - Or you can just put files of node-webkit in the same directory with your package.json and then distribute the tree. When nw executable is started it will look for package.json in the same directory. (on OSX it's the same level directory with
node-webkit.app
). This is the recommended way if the size of your files are big. - nodebob is a build tool for node-webkit that automates a release of your node-webkit application in windows environment. Currently in v0.1, written in windows batch script.
- nwjs-builder-phoenix, nw-builder & grunt-nw-builder Lets you build your node-webkit apps for mac, win and linux with grunt. They will download the prebuilt binaries for a specific version, unpacks it, creates a release folder, creates the app.nw file for a specified directory and copies the app.nw file to where it belongs
- Nuwk! Nuwk! makes it easy to create Mac Applications based on node-webkit, simplifying testing and building procedures. It takes care of creating the executable, attaching the app icon and configuring the plist file accordingly. (very alpha stage)
- generator-node-webkit is a yeoman generator to develop node-webkit applications and create packages for mac, linux and win.
-
lein-node-webkit-builder It's similar to
grunt-node-webkit-builder
, will download the binaries automatically and let you build on multi-platforms, but it runs as a Leiningen plugin, more suitable for people working with ClojureScript. - Web2Executable It's a full, cross-platform, opensource GUI packaging app that makes a single binary out of the web app, ready to use out of the box. It massively simplifies packaging apps and works with the Phaser game library. Works on Mac OSX, Linux and Windows using Pyside. It's in beta, so feedback and contributors are very welcome.
- nwjs-shell-builder - nwjs shell script builder for nwjs (node-webkit) applications. This script can be easily integrated into your build process, it will download nwjs 32/64bit for Linux, Windows and OSX and build packages for all 3 platforms from given source directory.
Many people are (understandably) concerned about what end-users need to do in order to run an app. If users receive a .nw
alone, they will naturally need nw
installed (or at least unzipped) in order to run it. But, with nw
, you can merge the .nw
file with the nw
executable.
In general, it's recommended to offer a .nw
for download, and optionally "merged" versions for the platforms where this makes things simpler.
Two things should be noted:
- The end result will not be a single executable, you must also include some DLLs in your zip-file.
- The resulting executable from the merge will still be readable by archiving software, such as WinZip.
Here's how to do it on Windows. In a console, type this:
copy /b nw.exe+app.nw app.exe
Then, all you have to do is zip app.exe and required DLLs, and distribute them. Yes; this does mean that the app will have a private copy of nw
, but there's nothing wrong with that. It also means that you will have to create one package for each platform you would like to support, or simply offer the .nw
alone for the other platforms.
And please also note that the nw.pak
must also be distributed along with the app.exe
.
Important note: if you are using native modules, your .exe
file shall be named nw.exe
as detailed in Using Node modules. Additional information is available at #199.
On Linux, it's similar:
cat `which nw` app.nw > app && chmod +x app
Then, you'll have to make a package for various packaging systems with dependencies as the nw
package. Were you to make a .deb package this way, for instance, the user would not have to install the nw
package separately.
And please note that the nw.pak
file must also be in the same directory with the app
file, otherwise you would expect blank page for some features.
Eventually, we will provide scripts which do this automatically for various package systems. You'll have to figure it out yourself until then.
Following guides apply to nw >= 0.2.4
On OS X, the node-webkit.app
is a directory that can be easily changed. To make nw automatically open your app, you need to put your app file under Contents/Resources
and name it app.nw
. The bonus over other platforms is that app.nw
does not need to be a zip file, if you want to speed up startup, you can make app.nw
your app's directory.
And you need to modify following files to make a real distribution of yours:
-
Contents/Resources/nw.icns
: icon of your app. -
Contents/Info.plist
: the apple package description file.
About the Info.plist
file, you can view Implementing Cocoa's Standard About Panel on how this file will influence your app and what fields you should modify.
Starting from v0.10.0, icudtl.dat
need to be shipped on all the 3 platforms, and icudt.dll
is not needed anymore.
Apart from the binary files, there're some other files you should also ship, see instructions for different platforms below.
And since the binary is based on Chromium, multiple open source license notices are needed including the MIT License, the LGPL, the BSD, the Ms-PL and an MPL/GPL/LGPL tri-license. (This doesn't apply to your code and you don't have to open source your code)
The nw.pak
and icudt.dll
must be shipped along with nw.exe
, the former one contains important javascript lib files, and the latter one is a important network library.
ffmpegsumo.dll
are media library, if you want to use <video>
and <audio>
tag, or other media related features, you should ship it.
libEGL.dll
and libGLESv2.dll
are used for WebGL and GPU acceleration, you had better ship them. And D3DCompiler_43.dll
and d3dx9_43.dll
as well if you want to make sure WebGL works on more hardware. These 2 files are from DirectX redistributable.
nw.pak
must be shipped with nw
. If you want media features, also ship libffmpeg.so
.
Just ship the node-webkit.app
would be fine, you don't need to care for other things.
After packaging app.nw
into nw.exe
in the above way, you still have to ship app.exe
with nw.pak
and some *.dll
files to the end users. It's still possible to improve the result.
Enigma Virtual Box is a software that 'enables application files and registry to be consolidated in a single executable file'. It's free for personal and commercial use.
Attention! "Enigma Virtual Box" and all accompanying files are licensed "AS IS" without warranties as to performance or merchantability or any other warranties whether expressed or implied. You use this way at your own risk! There may or may not be some issues with the program generated.
- Download and install the software.
- Open 'Enigma Virtual Box' from start menu or the program folder.
- Browse and choose the
app.exe
main program file in theEnter Input File Name
blank. - Drag (or use the 'add' button to select and add) all the other
*.dll
files andnw.pak
into the 'Files' blank. When the 'Select Folder' panel alerts, choose '%DEFAULT FOLDER' (the default value in fact) and press 'OK' button. - Press 'File Options', choose 'Compress Files', and 'OK' if you like.
- Some other configures if you know what you are doing.
- Press the big 'Process' button in the main panel.
- After all things done, you can press 'Close' and exit Enigma Virtual Box.
- There should be a new
app_boxed.exe
in the program folder now.
Now you can move and distribute the single app_boxed.exe
to anywhere, without any nw.pak
and *.dll
files.
Alternatively, for batch bundling, there is also a small Node integration module enigmavirtualbox. It even automatically downloads and locally unpacks the Enigma Virtual Box distribution. For this, install Node and NPM and run in your Windows terminal:
npm install -g enigmavirtualbox
-
enigmavirtualbox gen app.evp app_boxed.exe app.exe nw.pak icudtl.dat ffmpegsumo.dll libEGL.dll libGLESv2.dll
(generate configuration) -
enigmavirtualbox gui app.evp
(optionally post-edit configuration) -
enigmavirtualbox cli app.evp
(execute bundling process in batch)
The generated configuration file app.evp
can be stored so you
can repeat step (4) arbitrary times.
Instead of packaging your app in one exe file, you can create a setup which contains all necessary files. A free software for easily creating setups is Inno Setup: http://www.jrsoftware.org/isinfo.php
An example for a setup configuration can be found here: https://github.com/SSilence/sum/blob/master/setup.iss