Node.js Packer

Packing your Node.js application into a single executable.

Features

It takes less than 5 minutes to compile any project with node-packer.

You won't need to modify a single line of code in your application, no matter how you developed it as long as it works in plain node.js!

• Works on Windows, macOS and Linux
• Creates a binary distribution of your application
• Supports natively any form of require, including dynamic ones (e.g. require(myPath + 'module.js')
• Native C++ modules are fully supported
• Open Source, MIT Licensed

Download

Stable Releases

Here is the latest stable Node.js Packer release:

Unstable Pre-release

Whenever the master branch CI succeeded, a Node.js Packer pre-release binary would be automatically generated. Here is the latest unstable pre-release build:

Install

Install on Windows

First install the prerequisites:

• SquashFS Tools 4.3
• Python 2.6 or 2.7
• Either of,
  • Visual Studio 2015 Update 3, all editions including the Community edition (remember to select "Common Tools for Visual C++ 2015" feature during installation).
  • Visual Studio 2017, any edition (including the Build Tools SKU). Required Components: "MSbuild", "VC++ 2017 v141 toolset" and one of the Windows SDKs (10 or 8.1).

Then download nodec-x64.exe.

Optionally, put it under C:\Windows or any other PATH directories. Open Visual Studio's "x64 Native Tools Command Prompt" and execute nodec --help therein.

Install on macOS

First install the prerequisites:

• SquashFS Tools 4.3: brew install squashfs
• Xcode
  • You also need to install the Command Line Tools via Xcode. You can find this under the menu Xcode -> Preferences -> Downloads
  • This step will install gcc and the related toolchain containing make
• Python 2.6 or 2.7
• GNU Make 3.81 or newer

Then download nodec-darwin-x64.

Run chmod +x to give it execution permissions and execute ./nodec --help.

Additional Notes on Build failure in macOS XCode 11

According to recent Travis Build, the test cases will fail shortly after its launch occurs when the Build Environement is XCode 11. Currently, it is not known whether the issue is caused by XCode 11 or other factors within Travis CI that may not impact on actual macOS deployment.

Therefore, the build environment for macOS under Travis is XCode 10.2 so as to ensure the test case can be successfully executed and completed.

Install on Linux

First install the prerequisites:

• SquashFS Tools 4.3
  • sudo yum install squashfs-tools
  • sudo apt-get install squashfs-tools
• gcc and g++ 4.9.4 or newer, or
• clang and clang++ 3.4.2 or newer
• Python 2.6 or 2.7
• GNU Make 3.81 or newer

Then download nodec-linux-x64.

Run chmod +x to give it execution permissions and execute ./nodec --help.

Additional Notes on the compatibility between RHEL based (CentOS) / Ubuntu

It is known that the default repo for Red Hat and CentOS distros contains a very outdated gcc / g++ (3.8.5) while the latest Long Term Support (LTS) of Ubuntu as of 15 Feb 2018 (Ubuntu 18.04 LTS) contains a relatively updated gcc / g++ (7.3.0).

It is known that compilation can fail when using unsupported configuration where the version of prerequisites is older than prescribed.

Therefore, it is crucial for the users of Red Hat based distros to install gcc / g++ outside from official repos. For starters, one may look at:

• https://developers.redhat.com/blog/2018/07/07/yum-install-gcc7-clang/
• http://blog.stevedoria.net/20180214/how-to-install-gcc-7-on-centos-7

Additionally, binaries that are compiled from Ubuntu 18.04 LTS is known NOT to work in Red Hat 7 based distro (Including CentOS) due to 'glibcxx_3.4.20' not found' related error. However, binaries that are compiled from either Red Hat or CentOS 7 are known to work with Ubuntu 18.04 LTS based on my internal experiment.

Having said that, I will still recommend that binaries distributors should compile 2 versions for Linux where one caters for RHEL based and the other for Ubuntu based.

Additional Notes on Build failure in Linux

According to recent Travis Build, Linux has been failing to build since nodec-1.6.0-10.16.0 (Node.js 10.16.0). The root cause is yet to be determined, and the last known good build is 10.15.3 which can be downloaded here: https://github.com/slee047/node-packer/releases/tag/1.6.0-10.15.3-1

The issue can be found here: https://github.com/slee047/node-packer/issues/11

NOTE: This gz file (nodec-darwin-x64.gz) contains an outdated version of nodec (nodec 1.5.0 with Node.js 8.3.0). The original maintainer did not specify how to build this repo into single executable, therefore newer versions can only be run on source code directly.

Usage

nodec [OPTION]... [ENTRANCE]
      --current                    Uses the current Node.js release
      --lts                        Uses the LTS Node.js release
  -r, --root=DIR                   Specifies the path to the root of the application
      --output=FILE                Specifies the path of the output file
  -d, --tmpdir=DIR                 Specifies the directory for temporary files
      --clean-tmpdir               Cleans all temporary files that were generated last time
      --keep-tmpdir                Keeps all temporary files that were generated last time
      --make-args=ARGS             Passes extra arguments to make
      --vcbuild-args=ARGS          Passes extra arguments to vcbuild.bat
  -n, --npm=FILE                   Specifies the path of npm
      --skip-npm-install           Skips the npm install process
      --debug                      Enables debug mode
  -o, --dest-os=OS                 Specifies the destination operating system (enum: win mac solaris freebsd openbsd linux android aix)
  -a, --dest-arch=ARCH             Specifies the destination CPU architecture (enum: arm arm64 ia32 mips mipsel ppc ppc64 x32 x64 x86 s390 s390x)
      --quiet                      Enables quiet mode
  -v, --version                    Prints the version of nodec and exit
  -h, --help                       Prints this help and exit

Note: if ENTRANCE was not provided, a single raw Node.js interpreter executable would be produced.

Note: To compile to 32-bit windows OS compatible programs on a 64-bit machine, you should use a x64 x32 cross compiling environment. You should be able to find it in your Start Menu after installing Visual Studio. Also, you have to use a 32-bit Node.js, because the arch information is detected via node -pe process.arch.

Examples

Compile a CLI tool

git clone --depth 1 https://github.com/jashkenas/coffeescript.git
cd coffeescript
nodec bin/coffee
./a.out (or a.exe on Windows)

Compile a web application

git clone --depth 1 https://github.com/eggjs/examples.git
cd examples/helloworld
npm install
nodec node_modules/egg-bin/bin/egg-bin.js
./a.out dev (or a.exe dev on Windows)

Learn More

How it works

• Node.js Packer: compiling your Node.js application into a single executable.

Comparing with Similar Projects

Cross Compilation

nodec also support cross-compilation. Since node.js is built from sources you will need to setup properly a toolchain in order to get valid compilers to produce binaries for the destination platform.

You can easily do this with by using crosstool-ng or any other tool you like.

Once you're done with the build of a valid toolchain (don't forget to enable c++ if you use crosstool-ng which by default excludes it) you will be able to compile properly. Just set-up your environment so that it will know to use your cross-compile toolchain rather than your system's default build tools.

An example (you may need to adjust values or specify additional variables):

export AR="x86_64-unknown-linux-gnu-ar"
export CC="x86_64-unknown-linux-gnu-gcc"
export CXX="x86_64-unknown-linux-gnu-g++"
export LINK="x86_64-unknown-linux-gnu-g++"
export CPP="x86_64-unknown-linux-gnu-gcc -E"
export LD="x86_64-unknown-linux-gnu-ld"
export AS="x86_64-unknown-linux-gnu-as"
export CCLD="ax86_64-unknown-linux-gnu-gcc ${TARGET_ARCH}"
export NM="x86_64-unknown-linux-gnu-nm"
export STRIP="x86_64-unknown-linux-gnu-strip"
export OBJCOPY="x86_64-unknown-linux-gnu-objcopy"
export RANLIB="x86_64-unknown-linux-gnu-ranlib"
export F77="x86_64-unknown-linux-gnu-g77 ${TARGET_ARCH}"
unset LIBC

#Define flags
#export CXXFLAGS="-march=armv7-a"
export LDFLAGS="-L${CSTOOLS_LIB} -Wl,-rpath-link,${CSTOOLS_LIB} -Wl,-O1 -Wl,--hash-style=gnu"
export CFLAGS="-isystem${CSTOOLS_INC} -fexpensive-optimizations -frename-registers -fomit-frame-pointer -O2 -ggdb3"
export CPPFLAGS="-isystem${CSTOOLS_INC}"
# export CCFLAGS="-march=armv7-a"

#Tools
export CSTOOLS=/Volumes/crosstools/x86_64-unknown-linux-gnu
export CSTOOLS_INC=${CSTOOLS}/include
export CSTOOLS_LIB=${CSTOOLS}/lib
#export ARM_TARGET_LIB=$CSTOOLS_LIB
# export GYP_DEFINES="armv7=1"

#Define other things, those are not 'must' to have defined but we added
export SHELL="/bin/bash"
export TERM="screen"
export LANG="en_US.UTF-8"
export MAKE="make"

#Export the path for your system
#export HOME="/home/gioyik" #Change this one with the name of your user directory
export PATH=${CSTOOLS}/bin:/usr/arm-linux-gnueabi/bin/:$PATH

To-do

• Eliminate dependending on an outside Node.js and npm when compiling
• Be able to use a custom icon and file description for the executable output. maybe an icon file in the package root directory.
  • #54
• Add options to select items to deliver
  • Ppt out zlib/openssl for system libraries
  • Incl and ICU
  • Debug facilities
• Add options to select compression-method
  • Optionally xz the final product
• Detect simultaneous runs of nodec
  • #31
• Warn the user that some symbolic link links to the outside of the project
  • Add a check procedure at compile time
  • #37
• Cross-compile
  • #36
  • Support ARM architecture
  • #26
• Make Docker images for compiler environments
• Generate Windows-less Cmd-less Windows applications via /subsystem=windows
• Drop the external dependency of mksquashfs
  • i.e. Give libsquash the ability to mksquashfs
• Support library only projects
  • #39

Authors

Minqi Pan et al.

License

MIT

See Also

• Libsquash: portable, user-land SquashFS that can be easily linked and embedded within your application.
• Squashfs Tools: tools to create and extract Squashfs filesystems.