Relocatable Node.js on Windows

Process to Create a Portable Node Environment

Node.js, with its V8 JavaScript Engine, has proven to be remarkably resilient, with regular updates and improvements. Its success is, in no small part, assisted by the Node Package Manager (NPM). The process described here will create an xcopy-deployable (relocatable / portable) Node and NPM environment, suitable for any Node development, without affecting the Windows Registry, or other Node environments. It can also be used for cross-platform Electron GUI development.

Table of Contents

Requirements — You will need the following knowledge and/or functionality…

Command-line skills, using either the Command Prompt or PowerShell.

File system navigation and the concept of ‘current working directory’.

Directory and file manipulation (create/rename/copy/delete).

Command execution and passing arguments or options (switches).

Environment variables and PATH in particular.

Obtaining & Configuration Node

No official portable (relocatable) version of Node with NPM seems to exist, but NodeJS Portable provides a Portable Apps-based version with NPM, which may not be up to date (last updated 2 years ago). A few pages on the web describe processes by which you can manually create a standalone, portable Node, also with NPM, but they are generally incomplete, or out of date.

IMPORTANT Alternatively…

You can skip all of the following, and simply download the .msi installer for Windows, and install Node on your PC, in which case node and npm commands will be in your PATH. This is not unreasonable — you can use Node for many purposes.

However… if you want to create and manage your own portable version of Node for Windows, start by creating a directory where you want to store everything. The location and depth are not important, but remember that your Windows may have a 250 character path limit, and that NPM uses nested directories to manage packages. Spaces in the path will also make using it inconvenient. For example, we recommend you use a location like D:\rxnodejs. Set this directory as your current working directory. Below are example command lines (change the drive letter to suit your situation):

mkdir D:\rxnodejs
cd /d D:\rxnodejs

Now follow the rest of the instructions below. Keep in mind that we assume you have performed the above steps, and that any references to ‘rxNode’ refer to this directory as convenient shorthand.

NOTE — Architecture & Version Choices

You can decide whether to download either the 32-bit or 64-bit versions. Just make sure that everything else you install, that is related to Node, corresponds with this choice. The same applies to the version you choose: you can either install the 8.x.x LTS (Long Term Support) or 9.x.x Current versions. In these notes, we assume 32-bit and the 8.x.x LTS version.

Download LTS NodeJS

Node provides a ‘Long Term Support’ (LTS) version, and a ‘Current’ version, which is more cutting-edge, with the latest features. On the NodeJS Home Page, you will see installer downloads for both. Instead of downloading one, simply note the version number for the LTS release, then go to the NodeJS Downloads directory, to download the latest version, e.g.: v8.x.x or v9.x.x. Inside a subdirectory of the version directory, e.g.: …/latest-v8.x/win-x86, you will find node.exe, which is what you download to the Node directory you created above. Example result path:

   D:\rxnodejs\node.exe

Although that takes care of Node, you will eventually want to install some libraries / modules / packages, or even complete Node applications. Node by itself is quite capable (see Node 8 API, or Node 9 API), even without additional third party libraries.

NOTE — Zip File Version

In the latest v8.x.x, or v9.x.x directories, you will find .zip and/or .7z versions of the NodeJS distribution. These include NPM, and can simply be extracted and used (they have a nodevars.bat file that sets some environment variables and the PATH), but NPM will still use a npm-cache directory under your ‹user-home›\AppData\Roaming\npm-cache directory. This is not automatically bad, but if you do not like it, then you should avoid that route.

Test Driving Node

You can now run JavaScript on the command line, and use any of the many built-in modules, like the http module. When node is run without arguments, it enters a REPL (Read-Eval-Print Loop), where you can enter JavaScript statements and expressions. Press Ctrl-C twice, press Ctrl-D, or type .exit to terminate the REPL.

Alternatively, save your JavaScript in a ‹name›.js file, and execute it with: ‘node ‹name›.js’. The ‘.js’ part is optional, so ‘node ‹name›’ will also work.

To illustrate the appeal of Node, however, you can create the following file, called hello-web.js. This will create a simple web server, without the need to download and install any additional packages. This is the canonical Node version of a “Hello World” application.

`hello-web.js` — Simple Web Server with Node.js

//[file:hello-web.js] - Simple Web Server with Node.js
//
var http = require('http');
const util = require('util');
// const opn = require('opn');

var port = 8765; // allow through your firewall.
var title = "Hello World from Node.js";
var html = 
   "<html><head><meta charset=\"UTF-8\">\n" +
   "<title>%s</title>\n" +
   "</head><body>\n" +
   "<h1>Hello World #%d</h1>\n" +
   "</body></html>";
var req_no = 0;

// Dumb web server, which responds with "Hello World" to all requests.
//
var httpd = http.createServer(function (request, response) {
   response.writeHead(200, {"Content-Type": "text/html; charset=utf-8"});
   response.write("<!DOCTYPE html>\n");
   response.write(util.format(html, title, ++req_no));
   response.end();
});

httpd.listen(port);

console.log("Node.js server listening on http://localhost:%d/", port);
console.log("Press Ctrl-C to terminate the server.");
// opn('http://localhost:' + port); // optional

You run your new web server with the following command. You may have to allow it when your Windows Firewall message pops up. And of course, node.exe must be accessible.

node hello-web.js

Point your browser to http://localhost:8765, which will issue an HTTP request, and it should receive a response. Once you have installed NPM, or used the *.zip version, you can uncomment the lines concerning the opn package (which we assume you installed) with:

npm install -g --save opn

Then the script will open your browser automatically to the right port to display the “Hello” page.

Installing Node Package Manager

The de facto package manager is the Node Package Manager (NPM), which will automatically handle dependencies. On Windows, by default, it caches downloads in your %APPDATA% directory. We shall try and convince it otherwise.

Download & Extract NPM

The NPM Releases page may be a bit confusing, but scroll down until you see the highest numbered “Latest release” button, coloured green. Under the Assets heading, download the ‘Source code (zip)’ file to a convenient location (the filename will be something like: npm-5.6.0.zip).

Create a new directory under your rxNode directory, called node_modules, e.g.:

mkdir D:\rxnodejs\node_modules

Now, extract the downloaded zip file to this directory. The result will be something like:

   D:\rxnodejs\node_modules\npm-5.6.0

The versioning on the name must be removed, so rename the directory. The result looks like this in our example:

   D:\rxnodejs\node_modules\npm

Inside the .\node_mdules\npm\bin directory are two batch files, called npm.cmd and npx.cmd. They should be copied to the same directory where node.exe resides:

cd /d D:\rxnodejs
for %F in (npm,npx) do copy node_modules\npm\bin\%F.cmd .

Due to the code inside these batch files, they are useless unless copied next to node.exe.

NPM Configuration

NPM, with default configuration, will use directories outside of this portable install. However, this can be overridden. First, create the etc and tmp directories in the directory that contains node.exe:

cd /d D:\rxnodejs
mkdir D:\rxnodejs\etc
mkdir D:\rxnodejs\tmp

Now create a file called npmrc inside the etc directory, containing the following, and save it.

`npmrc` — Global Portable NPM Configuration

cache = ${NODE_ENV}\.npm
tmp = ${NODE_ENV}\tmp
prefix = ${NODE_ENV}
userconfig = ${NODE_ENV}\.npmrc
init-module = ${NODE_ENV}\.npm-init.js

To test that the npm program correctly picks up this new configuration, you can run the following command, but only after you have created and run the Node Environment Batch Files below.

npm config ls -l

; cli configs
long = true
metrics-registry = "https://registry.npmjs.org/"
scope = ""
user-agent = "npm/5.6.0 node/v8.9.4 win32 ia32"

; globalconfig D:\rxnodejs\etc\npmrc
cache = "D:\\rxnodejs\\.npm"
init-module = "D:\\rxnodejs\\.npm-init.js"
prefix = "D:\\rxnodejs"
tmp = "D:\\rxnodejs\\tmp"
userconfig = "D:\\rxnodejs\\.npmrc"
...

It should output many lines, containing all configuration settings, and also show which ones have been overridden with respect to their default values. Only the first few, important lines, are shown above.

Normally, with an installed Node, you update your NPM regularly with:

npm install -g npm@latest

But you will get errors on Windows with this relocatable version. It will refuse to overwrite npm.cmd or npx.cmd:

npm ERR! path D:\rxnodejs\npm.cmd
npm ERR! code EEXIST
npm ERR! Refusing to delete D:\rxnodejs\npm.cmd: ...
npm ERR! File exists: D:\rxnodejs\npm.cmd
npm ERR! Move it away, and try again.

You will first have to a) manually delete npm.cmd and npx.cmd, then b) run npm-cli.js directly as argument to node. The following commands will accomplish these steps:

cd /d D:\rxnodejs
for %F in (npm,npx) do @del %F.cmd
node D:\rxnodejs\node_modules\npm\bin\npm-cli.js install -g npm@latest

This will automatically create new npm.cmd and npx.cmd batch files in the node.exe directory.

At any point, you can list globally installed packages, with the following command:

npm list --global --depth=0

If you installed the opn package, the output should be at minimum as follows (the version numbers may be different):

+-- npm@5.6.0
`-- opn@5.1.0

ATTENTION — Run NPM After Batch Files

Although this might be a bit confusing, it would probably be better to run all these NPM commands after you have created and run the batch files below, which make the whole environment portable. The commands will work without the batch files, however, except that the package caching (package downloads) will be placed under your home directory (C:\Users\…).

Node Environment Batch Files

For convenience, we can create batch files to set the relevant environment variables and modify the PATH for a session.

Node Environment Setup

This version simply sets the environment variables, and modifies the PATH of the current Command Prompt session. It does not matter from which directory it is executed, but it must remain in the same directory as the node.exe file.

rxnode-env.cmd — Set Node Environment and PATH

@echo off & setlocal enableextensions
:: [rxnode-env.cmd] Sets Node environment and PATH only.
::
:: You can try commenting out the `HOME` variable setting. There is
:: some indication that node.exe might make/use an `etc` (settings) 
:: directory in the executable`s directory, if the `HOME` variable
:: does not exist.
::
:: LICENCE: MIT — https://opensource.org/licenses/MIT
endlocal

:: Get this batch file's directory, and strip trailing backslash.
:: All other paths are set relative to this variable.
set NODE_ENV=%~dp0
set NODE_ENV=%NODE_ENV:~0,-1%

:: Set `HOME`, `HOMEPATH` and `NODE_PATH` variables. This is because
:: `npm` insists on caching files in your home directory.
set HOME=%NODE_ENV%
set HOMEPATH=%NODE_ENV%

:: The following should not be necessary, but we leave it here as
:: a comment in case you need it in the future.
:: set NODE_PATH=%NODE_ENV%\node_modules

:: Set the REPLs history file location.
set NODE_REPL_HISTORY=%NODE_ENV%\.node_repl_history

:: Prefix this directory to the `PATH` variable.
set PATH=%NODE_ENV%;%PATH%

:: Change the prompt.
set PROMPT=[node] $p$_$g$s

:EXIT

According to the Node documentation for modules, the NODE_PATH is not necessary any more, but is still supported. It is commented out in the batch file, so you can uncomment it if you find that your Node application does not work without it.

Node Shell Launcher

This is a batch file, suitable for double-click execution from within a file manager, that not only sets the required environment and PATH, but also launches a new Command Prompt:

rxnode-cmd.cmd — New Command Prompt with Node Environment

@echo off & setlocal enableextensions
:: [rxnode-cmd.cmd] Opens new Command Prompt with Node environment and PATH
::
:: LICENCE: MIT — https://opensource.org/licenses/MIT
::
setlocal enabledelayedexpansion

:: The following batch file only sets the environment and PATH.
call rxnode-env.cmd

:: Open a new Command Prompt window, with appropriate title.
setlocal
set PROMPT=[node] $p$_$g$s
start "Node Environment" /D %NODE_ENV% cmd.exe /K "node ^-^-version"

:EXIT
endlocal

Concluding Remarks

Once the above two steps have been completed successfully, you have a working Node and NPM. However, they will not be in your PATH. So you must either provide the full path to the Node executable every time you run it; or your current directory must be the rxNode directory; or you must modify your PATH variable (temporarily or permanently).

When you install packages “globally”, with the --global or shorter -g command-line switches, when this configuration is in effect, the executables (batch files on Windows) will be installed in the same directory as node.exe. The other files comprising the package will be in the top-level node_modules directory. Each module will have its own subdirectory.

In this way, it is also easy to have multiple copies of Node on your system.

Supplementary Tools

NPM uses Git to clone and update packages. For Windows, you can install Git for Windows, or download Portable Git.

Also, keep in mind that a few Node packages contain natively-compiled components. For that to work, you must have a C/C++ compiler installed and in your PATH, when you perform a ‘npm install ‹package›’. Visual Studio 2015/2017 Community Edition, or Visual Studio 2015/2017 Build Tools, should work, as long as you include the --msvs_version=2015 option as npm argument (or 2017). It is not possible to make Visual C/C++ portable.

Some packages depend on Python, which means there must be a python.exe in your PATH. Python can be made portable to some degree, or you can try this single-file executable (rename to python.exe and place next to node.exe). Alternatively, try WinPython Zero, which is small and portable; e.g. WinPython-32bit-3.6.3.0Zero.exe.

2018-01-11: Edited [jjc].
2018-01-11: Updated for Node 8.x and 9.x [brx].
2017-07-04: Created. [brx]