Published April 13, 2023

Node 16 is reaching end of life status this summer, and you should probably update to at least Node 18 if you haven’t already.

As a former Senior Software Engineer on Arcadia’s Frontend Infrastructure team, I recently upgraded a dozen applications from Node 16 to Node 18, and wanted to share some of the most common issues I think you’ll run into.

  1. Make sure you update all the different places Node actually gets installed, the local dev environment, the Docker image, and the CI and CD processes. If you don’t already rely on a Node Version Management tool, like nvm or n, now is a great time to start, this will force you to put a file in your repo defining the Node version everyone is using (if you’re 100% relying a Docker image, then this is irrelevant).
  2. Are you using AWS CodeBuild? If you are, the default amazonlinux2 image doesn’t work with Node 18. AWS does offer an amazonlinux3 image which supports Node 18, but this isn’t available on AWS CodeBuild yet. Switch to the latest Ubuntu image, standard:6.0.
  3. If you’re using the Github Action actions/setup-node for your CI, I suggest using Node version v18.15.0. This version of Node is preinstalled in the Ubuntu image if you’re using the ubuntu-22.04 runner image (or ubuntu-latest at the time of writing this), which means you can save some time and skip downloading from the Node distribution site (which has been known to time out from time to time…).
  4. If you are authenticating with a private npm registry and previously used the always-auth npm configuration option, remove that or your build will fail, as this configuration option was deprecated.
  5. The absolute most annoying issue you’re going to run into is a change in how peer dependency conflicts are treated. In older versions of npm (I’m making the assumption you’re installing npm alongside node with a version management tool or Docker image), peer dependency conflicts could result in some console spam on install, but normally didn’t block installation from completing. However, when you upgrade to a newer version of Node (and npm), this will change. If you’re upgrading an application that has been around a long time, you’re likely going to have a lot of peer dependency conflicts that will block installation, and chasing them all down is quite the hassle. There is a crappy workaround if you desire, but my suggestion is to take the time and just fix the conflicts.
    1. To chase down the proper versions, I often just went to the packages on GitHub and located the package.json/peer-dependency list. The console output from the npm error is quite frustrating to comprehend.
    2. Also mentally preparing you now, this is a whackamole problem. When you fix one and re-install, it’s gonna give you a new error to address.
  6. If you’re on Webpack 4 or even an early version of Webpack 5, you’ll need to upgrade. You’re going to run into an annoying unsupported hash error because the OpenSSL version changed in Node 18. Again, there is a gross workaround, but my suggestion is to just do the upgrade to the latest version of Webpack 5 (or make your life even better and switch to Vite).

Hope this note was helpful for anyone about to embark on their own Node upgrade.