Short version for the impatient: pnpm is faster and stricter than npm, and the strictness is the actual reason to switch. The speed is a nice bonus you stop noticing after a week.<\/p>\n
Longer version: I moved a client project off npm about eight months ago, mostly because our CI installs were taking four minutes and I was tired of watching the spinner. The install time dropped, sure. But the thing that actually mattered was a bug pnpm found on day one that had been sitting in that codebase for over a year. I’ll get to it.<\/p>\n
I’ve also hit enough sharp edges since then that I don’t recommend pnpm to everyone anymore. So this is the honest version, including the parts where I had to back out.<\/p>\n
npm gives you a flat pnpm stores every package version once in a global content-addressable store on your disk, then hard links the files into your project. Install the same version of Only That top-level The disk savings are real but oversold. On my machine, seven projects that all use roughly the same React and TypeScript versions went from about 4.2 GB of The install speed is similar. First install on a cold store isn’t dramatically faster than npm, because you’re still downloading everything. It’s the second, third and fortieth install that fly, since the files are already sitting in the store and pnpm just relinks them. Our CI went from around four minutes to about fifty seconds once the store was cached between runs. If you don’t cache the store in CI, you get most of npm’s install time back and you’ll wonder what the fuss was about.<\/p>\n Here’s what happened. The project imported This is a phantom dependency, and it’s a time bomb. The day that transitive dependency bumps its version, or drops npm install: fine, no complaints, ships to prod.<\/p>\n pnpm install: The fix was If you take one thing from this post: run Now the part most pnpm posts skip.<\/p>\n The ecosystem is full of packages that use dependencies they never declared. pnpm’s own docs admit this outright, which is why it hoists everything into Things that broke for me:<\/p>\n React Native. Metro’s resolver and symlinks have a long and unhappy history. I spent an afternoon on it, got it half-working, and went back to npm for that project. Not worth the fight.<\/p>\n Some older webpack setups that resolve loaders by walking up directories. If a tool assumes it can reach into a flat Postinstall scripts. pnpm 10 stopped running dependency build scripts by default, which is a good security decision and an annoying migration. If something silently stops working after install, that’s probably why:<\/p>\n You allowlist the packages you actually trust to run code at install time. I like this a lot more than the npm default of “everything runs, good luck,” but you will find out the hard way which packages need it.<\/p>\n This one cost me a genuinely stupid afternoon. My laptop had pnpm 9, CI had pnpm 10, the lockfile format changed between them, and the error message was not helpful about why.<\/p>\n Fix is one line in Corepack reads that field and uses exactly that version, so everyone on the team and every CI runner gets the same one. You can set it with The wrinkle: Corepack ships with Node from 14.19.0 up to but not including 25.0.0<\/a>. It’s not bundled with Node 25 anymore. If you’re on 25, install it yourself:<\/p>\n Yes, you install corepack with npm. The corepack README acknowledges the irony, which I appreciated.<\/p>\n I use pnpm by default now, but not always.<\/p>\n Single-file scripts and throwaway prototypes get npm, because it’s already there and I’m not going to think about a lockfile for something I’ll delete on Friday.<\/p>\n Anything React Native, as covered.<\/p>\n Libraries where I want to test what consumers actually experience. If most of my users are on npm with a flat Codebases where I’m the guest, not the owner. Switching a team’s package manager is a social decision more than a technical one, and doing it unilaterally in a PR is a great way to annoy people.<\/p>\n For monorepos it’s not close. pnpm workspaces are the reason I stopped dreading multi-package repos, and I got into the tradeoffs there in when I actually merge the repos<\/a>. Most of the client work I do<\/a> ends up as some flavor of monorepo, so this comes up constantly.<\/p>\n Pick one project. Not your most important one.<\/p>\n If it builds and the tests pass, you’re done, commit the If it turns into a mess, I moved a client project from npm to pnpm eight months ago. The install speed was fine. The phantom dependency it caught on day one was the actual win.<\/p>\n","protected":false},"author":2,"featured_media":495,"comment_status":"","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"rank_math_title":"","rank_math_description":"I moved a client project from npm to pnpm eight months ago. The install speed was fine. The phantom dependency it caught on day one was the actual win.","rank_math_focus_keyword":"pnpm vs npm","rank_math_canonical_url":"","rank_math_robots":"","footnotes":""},"categories":[165],"tags":[567,44,77,379,377,378,376,201],"class_list":["post-496","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-javascript","tag-corepack","tag-javascript","tag-monorepo","tag-node-js","tag-npm","tag-package-manager","tag-pnpm","tag-tooling"],"_links":{"self":[{"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/posts\/496","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/comments?post=496"}],"version-history":[{"count":0,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/posts\/496\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/media\/495"}],"wp:attachment":[{"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/media?parent=496"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/categories?post=496"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/tags?post=496"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}node_modules<\/code>. Every package your dependencies depend on gets hoisted up to the top level, one big pile, deduplicated where possible. It works. It’s also why node_modules<\/code> is the heaviest object in the known universe.<\/p>\nlodash<\/code> in twelve projects and you’ve got one copy on disk, twelve hard links. The pnpm docs on the symlinked structure<\/a> walk through the layout, but the short version is that node_modules<\/code> looks like this:<\/p>\nnode_modules\n\u251c\u2500\u2500 foo -> .\/.pnpm\/foo@1.0.0\/node_modules\/foo\n\u2514\u2500\u2500 .pnpm\n \u251c\u2500\u2500 bar@1.0.0\n \u2502 \u2514\u2500\u2500 node_modules\n \u2502 \u2514\u2500\u2500 bar -> <store>\n \u2514\u2500\u2500 foo@1.0.0\n \u2514\u2500\u2500 node_modules\n \u251c\u2500\u2500 foo -> <store>\n \u2514\u2500\u2500 bar -> ..\/..\/bar@1.0.0\/node_modules\/bar\n<\/code><\/pre>\nfoo<\/code> is at the top level, because foo<\/code> is what you actually put in your package.json<\/code>. bar<\/code> lives one level down, reachable only by foo<\/code>. Node’s resolution algorithm ignores symlinks and resolves to the real path, so this all just works without patching anything.<\/p>\nnode_modules<\/code> being nearly empty is the whole trick.<\/p>\nnode_modules<\/code> down to a 1.1 GB shared store. Nice. Also completely irrelevant to whether my code works. I mention it because every pnpm pitch leads with this number, and it’s the least interesting thing about the tool.<\/p>\nThe bug it found on day one<\/h2>\n
date-fns<\/code> in about six files. date-fns<\/code> was never in package.json<\/code>. It was in node_modules<\/code> because some other dependency pulled it in, npm hoisted it to the top, and Node happily resolved it.<\/p>\ndate-fns<\/code> entirely, your build breaks for reasons that have nothing to do with anything you changed.<\/p>\nCannot find module 'date-fns'<\/code>, six files, immediately.<\/p>\n\/\/ what the code did\nimport { format } from 'date-fns';\n\n\/\/ what package.json said\n{\n "dependencies": {\n "express": "^4.18.0",\n "react": "^18.2.0"\n \/\/ no date-fns anywhere\n }\n}\n<\/code><\/pre>\npnpm add date-fns<\/code> and moving on with my life. Took ninety seconds. But I would never have found it otherwise, and it had been sitting there since 2024. Multiply that by however many packages in your tree are quietly doing the same thing.<\/p>\npnpm install<\/code> on your project once, just to see what falls out. You don’t have to commit to anything.<\/p>\nWhere it bit me<\/h2>\n
node_modules\/.pnpm\/node_modules<\/code> by default as a compatibility hack. That gets you most of the way, but not all of it.<\/p>\nnode_modules<\/code>, symlinks confuse it.<\/p>\n# pnpm-workspace.yaml\nonlyBuiltDependencies:\n - esbuild\n - sharp\n<\/code><\/pre>\nPin the version or CI will humiliate you<\/h2>\n
package.json<\/code>:<\/p>\n{\n "packageManager": "pnpm@10.13.1"\n}\n<\/code><\/pre>\ncorepack use pnpm@latest<\/code> instead of typing it by hand.<\/p>\nnpm install -g corepack\ncorepack enable\n<\/code><\/pre>\nWhen I still reach for npm<\/h2>\n
node_modules<\/code>, testing under pnpm’s strict layout tells me my package works in a stricter environment than the one it’ll live in. Useful, but not the same as testing the real thing.<\/p>\nWhat I’d actually do this week<\/h2>\n
rm -rf node_modules package-lock.json\ncorepack enable\npnpm install\npnpm run build && pnpm test\n<\/code><\/pre>\npnpm-lock.yaml<\/code> and add the packageManager<\/code> field. If it doesn’t, read the missing-module errors carefully, because each one is a phantom dependency you’ve been shipping. That list is worth having whether or not you keep pnpm.<\/p>\nrm -rf node_modules pnpm-lock.yaml && npm install<\/code> puts you back exactly where you started. The whole experiment costs about ten minutes and there’s no version of it where you learn nothing.<\/p>\n","protected":false},"excerpt":{"rendered":"