Install and manage Node.js versions using PNPM
Introduction: Why Node.js Version Management Matters
When working on multiple projects that rely on different versions of Node.js, managing these versions becomes essential to avoid compatibility issues. You may encounter a situation where one project requires Node 14.x while another needs Node 18.x, leading to challenges when switching between projects.
Historically, developers have used version managers like nvm or asdf to handle this. However, with pnpm, you can now manage Node.js versions seamlessly as part of your package manager, avoiding extra tools and streamlining your workflow. This article will guide you through the process of setting up and managing Node.js versions with pnpm step by step.
What is pnpm?
pnpm is a fast, disk space-efficient package manager for JavaScript applications. It uses a unique symlink-based system to avoid duplicating packages, making it much faster and saving space compared to other package managers like npm or yarn.
One of the standout features of pnpm is its ability to handle Node.js version management without needing external tools. Let’s dive into how to leverage this functionality to manage different Node.js versions for your projects.
How to Install pnpm
Before managing Node.js versions with pnpm, ensure you have pnpm installed on your machine. You can install it using the following commands:
If you have npm installed:
npm install -g pnpm
I personnaly don't recommend this methods because it implies installing Node as well as NPM before installing PNPM. The idea is to install PNPM only in order to manage the node versions.
Using Homebrew (macOS):
brew install pnpm
Using Powershell (Windows)
Invoke-WebRequest https://get.pnpm.io/install.ps1 -UseBasicParsing | Invoke-Expression
Once installed, verify that pnpm is correctly set up by running:
pnpm --version
Using pnpm to Manage Node.js Versions
Step 1: Enable Corepack (Optional for Node 16.13+)
Starting from Node.js 16.13, the Node team introduced corepack, a tool that automatically manages package managers like pnpm, yarn, and npm. If you're running Node.js 16.13 or higher, you can enable corepack to manage pnpm versions automatically:
corepack enable
This is optional but recommended if you want to keep your package manager versions in sync across different environments.
Step 2: Install Node.js via pnpm
Once pnpm is installed, you can use it to install specific Node.js versions for your project. This is done through pnpm env.
For example, to install Node.js version 18.16.0, run:
pnpm env use --global 18.16.0
The --global
flag ensures that this version of Node.js is available system-wide. If you omit --global
, the Node.js version will only be available within the project directory where the command is run.
Step 3: Checking Node.js Version
After installing a version of Node.js, you can verify which version is currently active by running:
node -v
This should output the version you just installed.
Step 4: Managing Multiple Versions
You might have several projects requiring different versions of Node.js. pnpm makes it easy to switch between versions using the env use command.
For example, if Project A requires Node.js 16.x and Project B requires Node.js 18.x, you can switch between versions like this:
For Project A (Node.js 16.x):
cd /path/to/projectA
pnpm env use 16
For Project B (Node.js 18.x):
cd /path/to/projectB
pnpm env use 18
pnpm will automatically handle the Node.js version switch as you move between projects.
Step 5: Setting Node.js Version per Project with .npmrc
To ensure consistency across environments and for team collaboration, it's a good practice to lock the Node.js version in each project’s .npmrc file.
To specify a Node.js version for a project, you can add the following line to your .npmrc file:
node-version=18.16.0
This ensures that anyone working on the project will use the specified version of Node.js when running pnpm commands within that project’s directory.
Additional Commands and Tips for Managing Node.js Versions
Listing Installed Node.js Versions
To see all the installed versions of Node.js managed by pnpm, run:
pnpm env list
This will display the versions available both globally and locally (in the context of specific projects).
Uninstalling a Node.js Version
If you no longer need a specific version of Node.js, you can remove it using:
pnpm env rm 16
This removes Node.js version 16.x (or any version specified) from your system.
Updating Node.js
When a new version of Node.js is released, you can easily update your version using the same env use command:
pnpm env use --global 18.17.0
This will replace the currently installed version globally.
Troubleshooting
- Conflicting Node.js Versions: If you encounter issues with conflicting Node.js versions, ensure that you're not using another version manager (like nvm) in parallel with pnpm, as this may cause confusion.
- Project Version Discrepancies: Always check the .npmrc file or package.json in your projects to ensure the correct Node.js version is set, particularly in team environments.
Conclusion
Managing Node.js versions with pnpm simplifies the development process, especially when dealing with multiple projects that require different Node.js versions. By using pnpm env, you can easily switch between versions, set project-specific Node.js environments, and ensure consistency across teams without needing an external version manager.
With pnpm, Node.js version management becomes part of your workflow, allowing you to focus on building your projects rather than managing your development environment. Happy coding!