pnpm 12は設定のタイプミスでinstallが止まる！Rust版に上げる前に確認したい4つの変更

🙌 結論から

pnpm 12は中身がRustに置き換わった版ですが、コマンドや設定はpnpm 11のままなので、上げる作業そのものは軽めです。

ただ、気にしたほうがいい変更が4つあります。

• pnpm-workspace.yaml の知らない設定（タイプミス）がエラーや警告になる
• pnpm install --frozen-lockfile false が使えなくなった
• sudo で pnpm setup や pnpm self-update を動かすと失敗する
• 循環した依存があるリポジトリは、lockfileに一度だけ差分が出る

正直、「Rustで書き直し」と聞いたときは、モノレポごと壊れるんじゃないか・・・と身構えました(・_・;)

でも公式の案内を読むと、壊れる場所はかなり絞られていたんですよね。

この記事は、私が仕事のモノレポで上げる前に確認したことを、そのまま順番に並べています👍

📦 pnpm 12はRustで書き直された版

pnpm 12は、パッケージマネージャー本体をRustで書き直したメジャーバージョンです。

公式のリリースノートでは、コマンド・フラグ・設定・lockfileの形式はpnpm 11から引き継ぐ、という方針が書かれています。

いまはpnpm 11も並行してメンテナンスされていて、10月30日には 12.17.0 と 11.28.10 が同じ日に出ています👀

なので「11のままでもしばらくは大丈夫、でも12に移るなら今のうちに」という時期かもしれません。

インストールの方法も少し変わりました。

公式のインストールページには、スタンドアロンのスクリプトで入れた場合、pnpm 12は入れたあとはNode.jsがなくても動くと書かれています。

curl -fsSL https://get.pnpm.io/install.sh | sh -

npm経由で入れる場合は、pnpm パッケージ側にNode.js 18以上が必要です。

もうひとつ、さりげなくうれしいのが「プロジェクトに合わせたグローバルのbin」です！

プロジェクトでNode.jsのバージョンを固定していると、グローバルの node コマンドもその版で動くようになりました(^^)

どのパッケージをこの動きにするかは globalShims という設定で決められます。

🔥 設定のタイプミスでinstallが止まる

一番影響がありそうなのがここです。

pnpm 12からは、pnpm-workspace.yaml にpnpmが知らない設定が書いてあると、それを報告するようになりました。

しかも、ありそうな正しい名前を候補として出してくれます✨

リリースノートの例がまさに minimumReleaseAge のつづり間違いで、これまでは黙って無視されていたそうです。

つまり「1日待ってから新しい版を入れる」つもりで書いた設定が、実はずっと無視されていた・・・ということがありえたわけです。

これはちょっと怖いですね(´･ω･`)

動き方は2通りです。

• packageManager などでpnpmのバージョンを固定しているプロジェクト → ERR_PNPM_UNRECOGNIZED_WORKSPACE_SETTINGS で失敗する
• 固定していないプロジェクト → 警告だけ出る

なお、pnpm config のサブコマンドはこの理由では失敗しないとのこと。

私のところは packageManager で版を固定しているので、上げた瞬間にCIが止まる側でした。

なので、上げる前に pnpm-workspace.yaml を開いて、キーを1行ずつ公式の設定一覧と見比べました👀

pnpm 11で .npmrc から pnpm-workspace.yaml に設定を移したときに、ハイフンの名前（hoist-pattern）のまま残していないかも見ておくと安心です。

pnpm 11のcodemodはcamelCase（hoistPattern）に直してくれますが、手で移した部分はそのままになりがちなので・・・！

🔒 CIとsudoで引っかかりやすい2つ

1つ目は --frozen-lockfile false です。

pnpm 12では pnpm install --frozen-lockfile false という書き方がサポートされなくなりました。

lockfileの固定をオフにしたいときは、--no-frozen-lockfile を使います。

# pnpm 11まで
pnpm install --frozen-lockfile false

# pnpm 12から
pnpm install --no-frozen-lockfile

CIの設定ファイルやMakefile、package.json のscriptsに残っていないか、grepで探しておくと早いです👍

grep -rn "frozen-lockfile false" .github/ Makefile package.json

2つ目は sudo です。

pnpm setup や pnpm self-update のようなグローバルに書き込むコマンドを sudo 付きで動かすと、ERR_PNPM_SUDO_NOT_SUPPORTED で失敗するようになりました。

pnpm bin --global のような読むだけのコマンドは、これまでどおり動くそうです。

pnpm 11.21.0の時点で警告が出るようになっていて、12で本当にエラーになった流れですね。

Dockerfileの中や、昔書いたサーバーのセットアップ手順で sudo pnpm ... を使っている場合はここで止まります(・_・;)

私はDockerfileではrootのまま pnpm を呼んでいて、sudo は使っていなかったので影響なしでした。

👀 lockfileに一度だけ差分が出る

これはエラーではないんですが、レビューのときに驚きやすいところです。

pnpm 12では、peer依存の解決で循環をどこで切るかが固定になりました。

そのおかげでlockfileが毎回同じ形に決まるようになったんですが、既存のlockfileは、最初に解決し直したときに一度だけ差分が出ます。

既存のlockfileはそのまま読めるので、壊れるわけではありません。

ただ、依存を1つ足しただけのPRに、関係ないlockfileの大きな差分が混ざると「何これ？」ってなりますよね笑

なので私は、pnpm 12に上げるPRの中で pnpm install まで済ませて、lockfileの差分をそのPRに閉じ込めることにしました。

ほかにも、Linuxでは packageImportMethod: auto のときにreflinkより先にhardlinkを試すようになっています。

macOSはこれまでどおりcloneが先なので、Macで開発している分には気にしなくてよさそうです🙌

🔧 私の上げ方はこれ

上の4つを踏まえて、仕事のモノレポではこの順番で上げることにしました(｀・ω・´)

1. いまのpnpmが11.10.0以降か確認する

公式のインストールページでは、v11.10.0以降なら pnpm self-update で12に直接上げられると案内されています。

pnpm --version

2. 12を明示して上げる

ここは少し迷ったところです(・_・;)

pnpm 12のリリースノートには「npmの latest はまだpnpm 11を指しているので pnpm self-update latest-12 で入れて」とあります。

一方でインストールのページは、latest が12を指している前提で書かれていました。

書かれた時期の違いだと思いますが、どちらにしても12を明示すれば迷わないので、私はこう打っています。

pnpm self-update latest-12

packageManager でバージョンを固定しているプロジェクトの中で self-update を打つと、グローバルには入れずにその固定の値だけを書き換えます。

なので、プロジェクトの中で打てば package.json の差分が1行出るだけです👍

3. installして、出たものを順番に直す

pnpm install

ここで ERR_PNPM_UNRECOGNIZED_WORKSPACE_SETTINGS が出たら、候補として出た名前に直します。

lockfileの差分が出たら、そのまま同じPRにコミットします。

4. CIの書き方を見直す

--frozen-lockfile false と sudo pnpm をgrepで探して、あれば直します。

CIでは、pnpm 11から入っている pnpm ci（pnpm clean のあとに pnpm install --frozen-lockfile）にまとめておくと、オプションの書き方で迷わなくなります✨

5. ローカルでも1回だけ確認する

チームのメンバーには、pnpm --version で12になっているかだけ確認してもらいました。

packageManager を固定していれば、古い版で動かしたときにpnpm側が教えてくれるので、そこまで神経質にならなくて大丈夫だと思います(^^)

🔗 関連記事と使い分け

• npmからpnpmに切り替えたらnode_modulesが半分以下に！ … pnpmをまだ入れていない人はこちらから。乗り換えの手順を書いています
• pnpmのcatalogでモノレポの依存バージョンを1か所にまとめた話 … pnpm-workspace.yaml の書き方はこちら。今回のタイプミスの確認もこのファイルが対象です
• miseでNode.jsとPHPのバージョン管理を一本化！ … Node.jsの版をmiseで管理している人は、pnpm 12のグローバルbinの動きとどちらに任せるかを決めておくと混乱しません

パパ系Webエンジニア〜愛用ガジェット一覧 🛍️

この記事を書いている作業環境のガジェットを楽天ROOMにまとめています ✨ 在宅エンジニアのデスク作りの参考にどうぞ 🙌

楽天ROOMで見る

🎉 まとめ

pnpm 12は「Rustで書き直したけど、使い方はpnpm 11のまま」という上げやすいメジャーバージョンでした。

注意するのは、設定のタイプミスがエラーになること、--frozen-lockfile false と sudo が使えなくなったこと、lockfileに一度だけ差分が出ることの4つです。

個人的には、タイプミスを教えてくれる変更が一番ありがたいかも・・！

黙って無視されていた設定に気づけるので、それだけでも上げる価値はあると思います(｡•̀ᴗ-)✧

ただ、急いで上げないといけない理由がなければ、pnpm 11もまだメンテナンスされているので、CIの見直しができるタイミングでまとめて上げるのがいいと思います🙌

※ バージョン番号・料金・機能は今後も変わる可能性があります。最新情報は公式サイトをご確認ください👀