Knowing Your Workflow Tools: pnpm-only

Assure pnpm is the only package manager used in your node projects.

Photo by Álvaro Serrano.

The Opinionated TLDR

The pnpm-only-template repository on GitHub includes a shell script that configures your node project to exclusively use pnpm as its package manager. Also consider:

• Mastering the tools you employ in software development.
• Favor deep expertise in a focused set of tools over a cursory understanding of many.
• Favor constraining the workflow over documentation.

Introduction

I enjoy coding and software architecture, but dealing with the tools that facilitate that? Not so much. I used to get by knowing just the basics of each tool; just enough to “get the job done.”

However, I’ve learned much too late, that to have an effective workflow to do the things I like, I need to really understand the tools I use.

Taking a step back, it’s been a transformative experience to deep-dive into the tools that shape my coding process, starting with setting up and configuring node packages. The package manager I use for node projects is pnpm.

Assuring that only pnpm is used as the package manger for a given project goes beyond just documentation. Constraining the workflow itself is a more effective way to guide new developers, reducing the likelihood of them accidentally using the wrong package manager.

Enforcing pnpm as the Exclusive Package Manager

Ensuring that pnpm is the sole package manager for our projects required some research and community contributions. Special thanks to those who have shared insights on this topic.

Disabling yarn

Disabling yarn as a package installer was easiest.

Running only-allow in the preinstall script stops yarn, yarn add and yarn install: even with an un-initialized project. The results can be seen below.

$ yarn add {package}, yarn install or yarn
yarn add v1.22.19
info No lockfile found.
$ npx only-allow pnpm
╔═════════════════════════════════════════════════════════════╗
║                                                             ║
║   Use "pnpm install" for installation in this project.      ║
║                                                             ║
║   If you don't have pnpm, install it via "npm i -g pnpm".   ║
║   For more details, go to https://pnpm.js.org/              ║
║                                                             ║
╚═════════════════════════════════════════════════════════════╝
error Command failed with exit code 1.
info Visit https://yarnpkg.com/en/docs/cli/add for documentation
about this command.

Disabling npm

It takes a little more work to disable npm from installing packages because npm installs packages before calling the preinstall script.

To stop npm from installing packages, we needed to add to package.json:

// package.json
{
  "engines": {
    "npm": "Use pnpm instead of npm."
  }
}

and create a .npmrc files with engine-strict=true:

echo "# Stop npm from being used as the installer.
# The following was added to package.json
# { \"engines\": { \"npm\": \"Use pnpm instead of npm.\" } }
engine-strict=true" > .npmrc

Running npm install and npm add now shows the following error:

$ npm install
npm ERR! code EBADENGINE
npm ERR! engine Unsupported engine

All of this is done for you using the following shell script.

What Sort of Works and Other Options

Pnpm Used to Initialize a Project

If a project has already been initialized by running pnpm install, running npm results in an error:

$ npm install
npm ERR! Cannot set properties of null (setting 'peer')
npm ERR! A complete log of this run can be found in: ....

Remove npm (not always possible)

Removing npm from the developers machine is an option.

Script a Replacement (not recommended)

# create the file

echo -e '#!/bin/bash
echo "Please use pnpm."
exit 1' > npm && chmod +x npm

# you can run it as follows but calling

$ ./npm

# this still runs npm
$ npm

# WARNING: Adding the current directory as part of the PATH can
# be dangerous.
# prepend the current working directory to your path
# MUST be prepended so the npm script will override npm
echo 'export PATH=".:$PATH"' >> ~/.zshrc && source ~/.zshrc

What Doesn’t Work

Using Package.json packageManager Option

At the time of writing, there is an experimental packageManager option in package.json which doesn't seem to work yet.

Conclusion

Mastering your workflow tools is not just a nicety; it’s a necessity for efficient and effective software development. While documentation has its place, favor a workflow that’s designed to guide developers in the right direction. This is what the pnpm-only-template aims to achieve.