Maintenance support ends this month for Node.js version 0.10. In December, version 0.12 will also face losing maintenance support. As a result, critical bugs and security vulnerabilities will no longer be fixed. Therefore, it's recommended to upgrade from Node.js version 0.10 and 0.12 to either version 4 or 6 before the end of the year.

The following is a collection of recommendations on how to upgrade to newer Node.js versions. These recommendations are presented as a general tutorial to help guide you through the process of upgrading your applications to work with Node.js version 4 or 6. Even though the tutorial targets upgrading to version 4 and 6, it should still be an appropriate guide for upgrading to future releases of Node.js, as the methodologies will remain the same.

Pick the version of Node.js to use

Will it be version 4 or version 6? Have a discussion with others in your organization to answer this question. This decision may be driven by support for new language features in version 6 that your team desires to use. It could come down to identifying the version that you will get the best outside support for. Regardless of the decision, its often a good idea to be consistent and to depend on the same version of Node.js across an organization. Once you have identified the version that will be supported and used in production, you should proceed by installing it and testing your applications using it.

Install the Node Version Manager

On your development machine you should already have and be using nvm, if not, please install it. The next step is to install the latest minor release of the major Node.js release you plan to use. Below is an example of installing the latest major Node.js release for versions 4 and 6 using nvm.

$ nvm i v4$ nvm i v6

Assess Tests

In all likelihood, an application with 100% code coverage from tests will be able to update Node.js versions with fewer production bugs. In other words, when you execute all of the code paths of an application, detecting bugs from a change in the underlying Node.js release will be more likely to happen in development. Therefore, if you have time and adequate resources, it's recommended to increase the code coverage.

Once you are confident in the application tests or your manual testing abilities you can proceed by using the release of Node.js you plan to upgrade to, installing the latest dependencies, and running the tests. Below is an example of the commands to execute to perform these actions.

$ nvm use v6                ## Use latest version of Node.js version 6$ rm -rf node_modules/      ## Remove old dependencies$ npm i                     ## Install latest dependencies using Node.js version 6$ npm test                  ## Run tests

Hopefully, all of the tests pass and everything will work. Regardless of if all of the tests do pass, you should proceed by assessing your modules to ensure that they have support for the version of Node.js that you intend to use.

Assess 3rd Party Module Support

Before changing anything in your application, you should review the 3rd party modules that are required by the application. Look through each module's registry entry and ensure that it supports the version of Node.js that you plan to use. One way to determine if a module will work on a particular version of Node.js is to look at the engines property in the package.json file. The engines property isn't required to publish a module. Therefore, many modules in the npm registry are missing them. If that is the case, you can get a hint at what version of Node.js the module will work with by looking at the Node.js version that was used to publish the module. Below is a command that you can execute to print all of the Node.js versions used to publish the modules that are dependencies of the module in the current working directory.

curl -s $(npm info --json | json dependencies | json -ka | awk '{print "https://registry.npmjs.org/" $1}') -H "Accept: application/json" | json -ag versions | json -gMa -c "return this.value && this.value._nodeVersion" | json -ga value.name key value._nodeVersion

The above script assumes that you have json and curl installed. It prints the module name, its version, and the version of Node.js that the module author used to publish the module.

Another method to determine if a module works on a particular Node.js version is to look at its Travis CI configuration. For example, the .travis.yml configuration file used across the hapi organization contains a node_js entry like the following, which indicate hapi works with both version 4 and 6 of Node.js.

node_js:  - "4"  - "6"  - "node"

If a module doesn't work on the version of Node.js that you plan to upgrade to then, you should be a good Open Source citizen and file an issue for the module author to assess. Before doing this, you should test the module against the version of Node.js that you want to use. Below is an example of testing the hoek module. Similarly, other modules that you depend on should have a npm test script to execute.

$ git clone git@github.com:hapijs/hoek.gitCloning into 'hoek'...$ cd hoek && npm i && npm test

Review Node.js Changes

At this point, the version of Node.js running in development is the same version that you intend to use in production. Additionally, you ran the tests in your application against that version of Node.js. Finally, you reviewed any dependencies to check whether they will work with the same Node.js version. Before altering any code in the application, you should consider the changes made to Node.js since the release of the one used in production. The Node.js team does an excellent job maintaining a list of major changes between versions.

Review the following changes, depending on the version of Node.js that you are upgrading from and the version you intend to use.

• Changes from v0.10 to v0.12
• Changes from v0.10 to v4.x
• Changes from v4.x to v5.x
• Changes from v5.x to v6.x

After consideration of the above lists of changes, you should proceed by updating your application code to fix any issues caused by the above changes.

Update the application

Hopefully, the modifications you need to make to your application are trivial. Either way, you should try to avoid doing a massive refactor or using any new language features just yet. Instead, you should concentrate on getting the application into a stable state on the version of Node.js you picked to run in production.

Add engines Property

To indicate the version of Node.js that the application now supports, you should add or update the engines entry in the package.json. For example, if the application now works with version 4.0.0 or newer, the engines entry will look like the following.

"engines": {  "node": ">=4.0.0"}

Next Steps

At this point, you should have an updated version of your application working with the appropriate Node.js version. The next step is to submit your changes and move the application through whatever pipeline your organization has chosen. Congratulations and best wishes running the updated application in production.