近年、Node.js のパッケージマネージャーとして Yarn の人気が高まっています。特に Yarn v3 以降の Modern Yarn は、高速なインストール、プラグインによる拡張性、ワークスペース機能など多くの魅力を備えているため、開発現場での採用が進んでいます。

しかし、Yarn を導入する際、「どのようにインストールすればいいのか」「Corepack とは何か」「バージョンを固定する方法は?」といった疑問を持つ方も多いのではないでしょうか。この記事では、Yarn のインストールから Corepack の有効化、プロジェクトごとのバージョン固定まで、初心者にもわかりやすく段階的に解説していきます。

背景

従来、Node.js のパッケージマネージャーといえば npm が標準でしたが、パフォーマンスや依存関係の管理に課題がありました。そこで登場したのが Yarn です。Yarn は npm の互換性を保ちつつ、高速化やロック機能の強化を実現しました。

さらに、Yarn v2（Berry）以降では Plug'n'Play (PnP) や ゼロインストール といった革新的な機能が導入され、モダンな開発環境に適したパッケージマネージャーへと進化しています。しかし、これらの新機能を使うには、正しいインストール手順とバージョン管理が不可欠です。

Yarn のバージョンは大きく分けて以下の 3 つが存在します。

#	バージョン	別名	特徴
1	Yarn v1 (Classic)	Yarn Classic	npm 互換の従来型パッケージマネージャー
2	Yarn v2/v3/v4	Yarn Berry / Modern Yarn	PnP、ゼロインストール対応の次世代型
3	グローバル Yarn	-	システム全体にインストールされた Yarn

Yarn の管理方式の変遷

以下の図は、Yarn のインストール・管理方式の変化を示しています。

mermaidCopy codeflowchart TB
  old["従来の方式<br/>(npm install -g yarn)"] -->|課題| issue["バージョン管理が困難<br/>プロジェクト間で競合"]
  issue --> new["Corepack による管理<br/>(Node.js 組み込み)"]
  new --> benefit["プロジェクトごとに<br/>バージョンを固定可能"]
  benefit --> modern["Modern Yarn<br/>(v2/v3/v4) の活用"]

図の要点: Corepack により、プロジェクトごとに Yarn のバージョンを固定し、チーム全体で一貫した環境を構築できるようになりました。

課題

Yarn を導入する際、以下のような課題に直面することがあります。

インストール方法の多様性

Yarn のインストール方法は複数存在します。npm でグローバルインストールする方法、公式インストーラーを使う方法、Homebrew を使う方法など、選択肢が多いため「どれが正しいのか」がわかりにくいのです。

bashCopy code# npm を使ったインストール
npm install -g yarn

bashCopy code# Homebrew を使ったインストール (macOS)
brew install yarn

これらの方法では、システム全体に Yarn がインストールされるため、プロジェクトごとに異なるバージョンを使いたい場合に不便です。

バージョン管理の難しさ

複数のプロジェクトで異なるバージョンの Yarn を使いたい場合、グローバルインストールでは対応できません。プロジェクト A では Yarn v3、プロジェクト B では Yarn v1 を使いたいというケースでは、手動でバージョンを切り替える必要があり、非効率です。

Corepack の存在が知られていない

Node.js v16.10.0 以降には Corepack という機能が組み込まれています。Corepack を使えば、プロジェクトごとに Yarn のバージョンを自動で管理できるのですが、この機能がまだ広く知られていないため、活用されていないケースが多いのです。

以下の図は、Corepack を使わない場合と使う場合の違いを示しています。

mermaidCopy codeflowchart LR
  subgraph without["Corepack なし"]
    direction TB
    global["グローバル Yarn<br/>(1 つのバージョン)"]
    projA1["プロジェクト A"] -.->|バージョン競合| global
    projB1["プロジェクト B"] -.->|バージョン競合| global
  end

  subgraph with["Corepack あり"]
    direction TB
    corepack["Corepack"]
    projA2["プロジェクト A<br/>(Yarn v3)"]
    projB2["プロジェクト B<br/>(Yarn v1)"]
    corepack -->|自動切り替え| projA2
    corepack -->|自動切り替え| projB2
  end

  without -->|改善| with

図の要点: Corepack を使うことで、プロジェクトごとに適切な Yarn バージョンが自動的に適用され、バージョン競合の問題が解消されます。

解決策

これらの課題を解決するために、Corepack を使った Yarn のインストールとバージョン固定を推奨します。Corepack は Node.js に標準で含まれているため、追加のインストールは不要です。有効化するだけで、プロジェクトごとに Yarn のバージョンを管理できるようになります。

Corepack の有効化

Corepack はデフォルトでは無効になっているため、最初に有効化する必要があります。

bashCopy code# Corepack を有効化
corepack enable

このコマンドを実行すると、yarn、pnpm といったパッケージマネージャーが Corepack の管理下に置かれます。以降、yarn コマンドを実行すると、Corepack が自動的に適切なバージョンを選択してくれるのです。

Node.js のバージョン確認

Corepack は Node.js v16.10.0 以降に含まれています。まずは Node.js のバージョンを確認しましょう。

bashCopy code# Node.js のバージョン確認
node -v

もし v16.10.0 未満の場合は、Node.js をアップデートしてください。最新の LTS 版を使うことをお勧めします。

bashCopy code# nvm を使って最新 LTS 版をインストール (例)
nvm install --lts
nvm use --lts

Yarn のバージョン指定

プロジェクトで使用する Yarn のバージョンを package.json に記載します。これにより、チームメンバー全員が同じバージョンを使うことが保証されます。

jsonCopy code{
  "name": "my-project",
  "packageManager": "yarn@4.0.2"
}

packageManager フィールドに yarn@バージョン番号 を指定することで、Corepack が自動的にそのバージョンを使用します。

バージョンの自動インストール

package.json に packageManager を指定した状態で yarn コマンドを実行すると、Corepack が自動的に指定されたバージョンをダウンロードして使用します。

bashCopy code# Yarn を実行 (初回は自動ダウンロード)
yarn --version

出力例:

Copy code4.0.2

これで、プロジェクトごとに異なる Yarn バージョンを使い分けることができるようになりました。

Corepack による管理フロー

以下の図は、Corepack を使った Yarn のバージョン管理フローを示しています。

mermaidCopy codesequenceDiagram
  participant dev as 開発者
  participant corepack as Corepack
  participant pkg as package.json
  participant cache as Yarn キャッシュ

  dev->>corepack: yarn コマンド実行
  corepack->>pkg: packageManager フィールド確認
  pkg-->>corepack: yarn@4.0.2
  corepack->>cache: v4.0.2 がキャッシュ済みか確認
  alt キャッシュなし
    cache-->>corepack: なし
    corepack->>cache: v4.0.2 をダウンロード
  end
  cache-->>corepack: v4.0.2 を返す
  corepack->>dev: yarn v4.0.2 で処理実行

図の要点: Corepack は package.json の packageManager を読み取り、必要に応じて自動ダウンロードし、常に正しいバージョンの Yarn を実行します。

具体例

ここでは、実際のプロジェクトで Corepack を使って Yarn をセットアップし、バージョンを固定する手順を段階的に解説します。

新規プロジェクトでのセットアップ

新しいプロジェクトを作成し、Yarn v4 を使う例です。

ステップ 1: プロジェクトディレクトリの作成

bashCopy code# プロジェクトディレクトリを作成
mkdir my-new-project
cd my-new-project

ステップ 2: package.json の初期化

bashCopy code# package.json を作成
npm init -y

これで基本的な package.json が生成されます。

ステップ 3: packageManager フィールドの追加

package.json を編集して、packageManager フィールドを追加します。

jsonCopy code{
  "name": "my-new-project",
  "version": "1.0.0",
  "packageManager": "yarn@4.0.2"
}

この設定により、このプロジェクトでは Yarn v4.0.2 が使用されます。

ステップ 4: Corepack の有効化

bashCopy code# Corepack を有効化 (初回のみ)
corepack enable

このコマンドは、システム全体で一度だけ実行すれば OK です。

ステップ 5: Yarn の実行確認

bashCopy code# Yarn のバージョン確認
yarn --version

出力:

Copy code4.0.2

初回実行時は、Corepack が自動的に Yarn v4.0.2 をダウンロードします。2 回目以降はキャッシュから読み込まれるため、高速に動作します。

ステップ 6: 依存パッケージのインストール

bashCopy code# 依存パッケージをインストール
yarn add react react-dom

これで、Yarn v4.0.2 を使ってパッケージがインストールされました。

既存プロジェクトへの適用

既に npm や古い Yarn を使っているプロジェクトに、Corepack + 最新 Yarn を導入する例です。

ステップ 1: 現在の Yarn バージョン確認

bashCopy code# 現在の Yarn バージョン確認
yarn --version

たとえば、古い Yarn v1.22.x が入っている場合、このバージョンはグローバルインストールされたものかもしれません。

ステップ 2: グローバル Yarn の削除 (推奨)

Corepack を使う場合、グローバルにインストールされた Yarn は不要です。削除することで競合を防げます。

bashCopy code# npm 経由でインストールした Yarn を削除
npm uninstall -g yarn

bashCopy code# Homebrew 経由でインストールした Yarn を削除 (macOS)
brew uninstall yarn

ステップ 3: package.json に packageManager を追加

jsonCopy code{
  "name": "existing-project",
  "version": "1.0.0",
  "packageManager": "yarn@4.0.2",
  "dependencies": {
    "express": "^4.18.0"
  }
}

ステップ 4: Corepack の有効化

bashCopy code# Corepack を有効化
corepack enable

ステップ 5: Yarn の再インストール確認

bashCopy code# Yarn のバージョン確認
yarn --version

出力:

Copy code4.0.2

これで、プロジェクトは Yarn v4.0.2 で動作するようになりました。

ステップ 6: 依存関係の再インストール

bashCopy code# 既存の node_modules を削除
rm -rf node_modules

# Yarn でインストール
yarn install

Yarn v4 では、PnP モードがデフォルトになっている場合があります。従来の node_modules 方式を使いたい場合は、.yarnrc.yml で設定を変更します。

yamlCopy code# .yarnrc.yml
nodeLinker: node-modules

この設定により、従来通り node_modules ディレクトリにパッケージがインストールされます。

バージョンの切り替え

プロジェクトによって異なる Yarn バージョンを使い分ける例です。

プロジェクト A: Yarn v3 を使用

jsonCopy code{
  "name": "project-a",
  "packageManager": "yarn@3.6.4"
}

bashCopy code# プロジェクト A で Yarn 実行
cd project-a
yarn --version

出力:

Copy code3.6.4

プロジェクト B: Yarn v1 (Classic) を使用

jsonCopy code{
  "name": "project-b",
  "packageManager": "yarn@1.22.19"
}

bashCopy code# プロジェクト B で Yarn 実行
cd project-b
yarn --version

出力:

Copy code1.22.19

このように、Corepack を使えば、プロジェクトごとに異なる Yarn バージョンを自動的に切り替えて使うことができます。

チーム開発での活用

チーム全体で同じ Yarn バージョンを使うことで、「自分の環境では動くのに、他の人の環境では動かない」という問題を防げます。

チームメンバーへの共有手順

1. プロジェクトの package.json に packageManager フィールドを追加
2. README に Corepack 有効化の手順を記載
3. Git にコミット & プッシュ

markdownCopy code# セットアップ手順

1. Node.js v16.10.0 以上をインストール
2. Corepack を有効化: `corepack enable`
3. 依存パッケージをインストール: `yarn install`

これだけで、チームメンバー全員が同じ Yarn バージョンで開発できるようになります。

トラブルシューティング例

エラー: corepack: command not found

原因: Node.js のバージョンが古い、または Corepack が無効になっている

解決方法:

1. Node.js のバージョンを確認

bashCopy codenode -v

2. v16.10.0 未満の場合は Node.js をアップデート

bashCopy code# nvm を使ったアップデート例
nvm install --lts
nvm use --lts

3. Corepack を有効化

bashCopy codecorepack enable

エラー: Usage Error: This project is configured to use yarn@4.0.2

エラーメッセージ例:

vbnetCopy codeUsage Error: This project is configured to use yarn@4.0.2, but the current yarn version is 1.22.19

原因: グローバルにインストールされた古い Yarn が優先されている

解決方法:

1. グローバル Yarn を削除

bashCopy codenpm uninstall -g yarn
# または
brew uninstall yarn

2. Corepack を有効化

bashCopy codecorepack enable

3. 再度 Yarn を実行

bashCopy codeyarn --version

これで、package.json で指定されたバージョンが使われるようになります。

Yarn のバージョン別の比較表

どのバージョンを選ぶべきか迷った場合の参考にしてください。

#	バージョン	リリース時期	主な特徴	推奨用途
1	Yarn v1 (Classic)	2016 年〜	npm 互換、安定性重視	レガシープロジェクト、互換性重視
2	Yarn v2/v3	2020 年〜	PnP、ゼロインストール	モダンプロジェクト、高速化重視
3	Yarn v4	2023 年〜	PnP 改善、パフォーマンス向上	最新プロジェクト、最先端機能

選び方のポイント:

• 安定性重視: Yarn v1 (Classic)
• 高速化・モダン機能: Yarn v3 または v4
• 新規プロジェクト: Yarn v4 がおすすめです

まとめ

この記事では、Yarn のインストールから Corepack の有効化、プロジェクトごとのバージョン固定まで、段階的に解説しました。

重要なポイント:

• Corepack を使う: Node.js v16.10.0 以降に標準搭載されており、追加インストール不要
• packageManager フィールドを設定: package.json に記載することで、プロジェクトごとに Yarn のバージョンを固定できます
• グローバル Yarn は不要: Corepack を使う場合、グローバルインストールは推奨されません
• チーム全体で統一: バージョンを固定することで、開発環境の差異による問題を防げます

Corepack による Yarn 管理は、モダンな開発環境において非常に有効です。ぜひこの方法を試して、快適な開発体験を手に入れてください。

関連リンク

• Yarn 公式サイト
• Yarn v4 ドキュメント
• Corepack - Node.js 公式ドキュメント
• Node.js 公式サイト
• Yarn Berry (v2/v3/v4) 移行ガイド