So you want to upgrade your Node.js installation?
By Colin Ihrig

The v4 and v5 release lines of Node.js represent huge advancements in the Node.js project. The initial versions of these release lines came in September and October 2015, respectively. Compare that with the 0.12 and 0.10 release lines, which came into existence in February 2015 and March 2013, and you’re dealing with a significant delta in terms of the code base. Not only have Node’s APIs changed during that time, but V8, the JavaScript engine that drives Node, has also changed dramatically during the same time period.

V4 and v5 provide increased stability and performance, coupled with reduced memory consumption. And, of course, the new release lines include ES6 features such as let, const, template strings, arrow functions and more.

At this point, you’re probably asking yourself “How do I get my hands on a new version of Node?”

Getting a new version of Node.js

There are literally two bajillion ways to install Node.js. The simplest way is to visit the Node homepage or download page and download the installer for your system. You can choose from the latest long-term support (LTS) version or the latest stable version. You can also visit to download any previous version of Node. If you prefer to install using your operating system’s package manager, the Installing Node.js via package manager page likely has relevant instructions for you.

Another alternative is to build Node from source. Archived source code is available on the download page and at Of course, you can also access the source code where it lives on GitHub. The instructions for building from source vary by operating system, but detailed instructions are available in the project’s README.

One thing worth noting is that newer versions of Node require a C++11-capable compiler. If you’ve built an older version of Node from source in the past, but are unable to build a new version of Node, there is a good chance that upgrading your C++ compiler will help. The same applies to compiled addons from the npm registry. Up-to-date compiler requirements are specified in the project’s README.

At nearForm, we work extensively with 0.10 and v4, and we need to switch between different versions of Node frequently. To do this, we use a version manager such as nvm or n. A version manager allows you to rapidly switch between versions of Node from the command line. Personally, I prefer n for managing the system level installation on my machine. However, nvm allows you to set your Node version per shell instance, making it extremely useful for running multiple versions of Node at the same time.

Auditing an existing application

If you are starting a new project from scratch, then congratulations! You have a new version of Node and a blank slate. Happy coding.

Unfortunately, most people are not going to find themselves in that situation. After updating your version of Node, you must extensively test your code. Why? The answer is that there are now significant changes to the environment in which your application is running. Is your code using an API that has been removed, or even worse, changed very subtly? What about the 70 modules (on average) being installed with your application? How will they handle the version jump? What if the new version of Node has a bug that wasn’t present in the old version, and your code happens to trigger it? These are all uncertainties that need to be verified before you can confidently go to production with a new version of Node.

You need to have tests, and you need to run them. You need to understand your tests’ code coverage, and you need to aggressively working toward 100% code coverage. In fact, you need tests beyond 100% code coverage, because that still doesn’t prevent bugs.

So what else can you do besides run your tests? You should review the changes that have gone into the release you’re using. Each Node release is accompanied by a blog post. These blog posts describe notable changes and contain a complete list of the git commits that went into the release. This list links to the individual code changes and GitHub pull requests, so you explore each change in as much detail as necessary. The Node core team has also put together some useful documents that outline breaking changes. These documents are Breaking changes between v0.12 and next LTS release and API changes between v0.10 and v4, and they contain a list of changes that can potentially break your application when jumping from an old release line to a new release line.

If you’re coding at the C++ level, you’ll definitely want to check out the v8 API Changes document, which outlines the V8 C++ API changes going back to V8 3.22. You’ll also want to make sure that any native addons you develop are using Native Abstractions for Node.js (NAN)’s 2.x.x release line, as a massive rewrite occurred for v4+ compatibility. If one of your native dependencies has not been updated to support Node v4 yet, you should consider dropping it if possible.

Going to production

Once you’ve audited your application, updated any offending code, and gotten all of your tests passing, you should feel relatively confident about moving forward with a new version of Node. If you have access to a QA department, you should put your updated application through a full round of QA. If you want to play it extremely conservatively, try rolling out the new Node version to just a fraction of your production servers. You should probably run your tests one more time too… just in case.

The jump from 0.10 or 0.12 to v4 or v5 is sizable, but overall, I think you will find that it is not too bad. The core team has put significant effort into minimizing breaking changes.

Now you just need to update your application to use all the sweet new APIs and language features.

Subscribe to our monthly newsletter!
join the discussion