💻

環境構築|corepackとは?npm・yarn・pnpm等のパッケージマネージャーを統一(トラブルシューティング付)

    環境構築

corepackとは何ぞ

corepackとはパッケージマネージャーを管理するツールで、指定したパッケージマネージャを自動で使わせたり、指定外のパッケージマネージャを使えなくしたり、プロジェクトのパッケージマネージャーを統一化できるツール。

Node.jsの16.914.19以降ではデフォルトで搭載されています。(corepack -vを叩けば返答をくれるはず)詳細は下記の記事が参考になります。

corepack is 何?|Zenn

公式のGitHubやYarnのcorepack解説ページは下記を参照。

package.jsonにプロパティを追加することでマネージャーのロックが可能

{
  ...
  "packageManager": "yarn@3.2.3+sha224.953c8233f7a92884eee2de69a1b92d1f2ec1655e66d08071ba9a02fa"
}

上記のようにpackageManagerに値をセットすることで、上記であればプロジェクトのパッケージマネージャーをyarn@3.2.3にロックすることができます。公式で+sha224以降は推奨されているキャッシュ形式です。

SHA-224とは|「分かりそう」で「分からない」でも「分かった」気になれるIT用語辞典

例えば、上記のpackage.jsonのプロジェクトにて、yarn@1.22.22を使おうとすると下記のようなエラーを出してくれます。

error This project's package.json defines "packageManager": "yarn@3.2.3". However the current global version of Yarn is 1.22.22.

Presence of the "packageManager" field indicates that the project is meant to be used with Corepack, a tool included by default with all official Node.js distributions starting from 16.9 and 14.19.
Corepack must currently be enabled by running corepack enable in your terminal. For more information, check out https://yarnpkg.com/corepack.

このように、開発者によって利用するパッケージマネージャーが異なることによる依存関係の不具合等を無くしてくれるのが、corepackの良いところ。

corepackの利用方法

# nodeバージョンが`16.9`、`14.19`以上か確認
$ node -v

nodeバージョン16.914.19以上の場合

$ corepack enable yarn
$ yarn -v

corepackはまだ実験段階のようでオプトインでこちらから利用を明示しないといけません。yarn -vして、package.jsonpackageManagerプロパティにセットされたバージョンが返ってくれば完了。

corepackをインストールする必要がある場合

corepackのGitHubページ記載の通り手動インストール。

$ npm uninstall -g yarn pnpm
$ npm install -g corepack
$ corepack -v

グローバルにインストールしているyarnやpnpmをアンインストールした方が良い理由は、Yarnのcorepackページの方が丁寧に解説されていました。

You may notice by reading our installation guide that we don't tell you to run npm install -g yarn to install Yarn - we even recommend against it. The reason is simple: just like your project dependencies must be locked, so should be the package manager itself.

Installing Yarn as a global binary meant you always used whatever was the latest version published. Most of the time it worked fine, but every once in a while something was shipped that could impact the way your project was installed - be it a bugfix, new bug, or breaking change.

そもそもパッケージマネージャ管理をcorepackが担うイメージになるので、プロジェクトの依存関係をがっちりロックするためにも、その管理もcorepackが担当しないといけません。グローバルなYarn等があるとそっちにパスが向いたり、予期しないバグを生むことも...。

トラブルシューティング

corepack enable yarnしてもバージョンが変わらない

$ corepack enable yarn
$ yarn install

と実行しても、

error This project's package.json defines "packageManager": "yarn@4.2.2". However the current global version of Yarn is 1.22.22.

Presence of the "packageManager" field indicates that the project is meant to be used with Corepack, a tool included by default with all official Node.js distributions starting from 16.9 and 14.19.
Corepack must currently be enabled by running corepack enable in your terminal. For more information, check out https://yarnpkg.com/corepack.

が返ってくるばかりで、package.json通りのパッケージマネージャーを使えないというトラブル。

おそらく下記のように、コマンド実行後特に何の返答もないという人が多いかと思います。

user % corepack enable yarn
# 特に何の返答もなし...
user %

エラーの原因(結局エラーではない)

yarnのパスの問題です。corepackやyarnそれぞれのパスの向いている方向を見てみます。

$ which yarn
# /opt/homebrew/bin/yarn
$ which corepack
# /user/.nodenv/shims/corepack
$ which node
# /user/.nodenv/shims/node

筆者の場合は上記のように、yarnだけhomebrewにパスが向いていました。要はcorepack enable yarnをして何の反応もなかったのは、普通に成功していただけということだった。corepack use yarn@4.2.2すると、yarn@4.2.2を使ってインストールが成功していたので、CLI的にhomebrewのyarn@1.22.22を見ていただけということ。

この「homebrewでのインストールも影響する可能性がある」ということは、corepackのGitHubページには、きちんと忠告をしてくれていた。

First uninstall your global Yarn and pnpm binaries (just leave npm). In general, you'd do this by running the following command:First uninstall your global Yarn and pnpm binaries (just leave npm). In general, you'd do this by running the following command:
corepack|GitHub

npm uninstall -g yarn pnpm

# That should be enough, but if you installed Yarn without going through npm it might
# be more tedious - for example, you might need to run `brew uninstall yarn` as well.

「まずはグローバルなYarnやpnpmを消してね。このコマンドで十分なはずだが、npmを介さずにYarnをインストールした場合もっと面倒かも。例えばbrew uninstall yarnも必要かも。」という感じの意味で、前述の通りグローバルでyarnをインストールしているならアンインストール(or パスを調整)しておかないといけません。

②【緊急時】どうしても指定されたパッケージマネージャーのコマンドを使えない場合

どうしてもエラー回避できなかったり、パスの調整が難しい場合は、corepack use yarn@4.2.2でインストールさえできれば、npm run [コマンド]でも実行可能です。なぜnpmだけ可能か...

ちなみに作者の arcanis 氏は yarn のリードメンテナ。DESIGN.md によれば、npm だけが Node.js に標準バンドルされていて優遇されてるけど、他のパッケージマネージャも同等に first class citizen として扱いたい。
corepack is 何? 😋

という訳のようです...なんという優遇。

ただ、corepackでちゃんとマネージャーを管理しているのに、その管理下とは別のパッケージマネージャーを使うのはcorepackのメリットを潰してしまうので、時間があるときに調整すべきです。

【Tips】グローバルインストールのyarn・pnpmで面倒な事態にならないようにnodenvnodebrewを使おう

最後に補足で、初めからyarn等のパッケージマネージャーはnodenvnodebrew経由でインストールして、パスもそちらに向けておくことをおすすめします。

下記でnodenvを使った方法をまとめておきます。

nodenvインストール

インストールの説明は省略します。nodenv|GitHubをご参考に。インストールは終わった前提で説明を続けます。

nodenv-yarn-install|GitHubを使って、nodenv install時にyarnも同時にインストールされるようにする。

$ mkdir -p "$(nodenv root)/plugins"
$ git clone https://github.com/pine/nodenv-yarn-install.git "$(nodenv root)/plugins/nodenv-yarn-install"

上記で、nodenvのルート直下のpluginsディレクトリに必要なファイルをgit cloneします。

あとは、nodenvで参照していたnodeバージョンを一度uninstallして、もう一度nodenv install [version]すれば...

...
Installing Yarn...
Installed Yarn 1.22.22

ときちんとyarnもインストールされていて、which yarnすれば/user/.nodenv/shims/nodeが返ってくるはず。もしまだグローバルにインストールしたyarnにパスが向いていれば、アンインストールをしたり、パスをnodenvの方に向き直したり調整しましょう。