Yarn を使ったプロジェクトで、「そろそろ Yarn Berry に移行したいけど、どうすればいいんだろう」と悩んでいませんか。

Yarn Classic（v1 系）から Yarn Berry（v2 以降）への移行は、パッケージ管理の効率化やモダンな機能を活用できる絶好の機会です。しかし、移行手順を誤ると依存関係の解決に失敗したり、既存のスクリプトが動かなくなったりする可能性があります。

本記事では、yarn set version コマンドを正しく使って、Yarn Classic から Yarn Berry へスムーズに移行する手順を、初心者の方にもわかりやすく解説いたします。実際のコマンド例やエラー対処法も含めて、段階的にご説明しますので、安心して移行作業を進められるでしょう。

背景

Yarn Classic と Yarn Berry の違い

Yarn は JavaScript のパッケージマネージャーとして、npm の代替として 2016 年に登場しました。初期のバージョンである Yarn Classic（v1 系）は、高速なインストールと lock ファイルによる再現性の高さで人気を集めました。

しかし、2020 年に Yarn Berry（v2 以降）がリリースされ、アーキテクチャが大きく刷新されたのです。Yarn Berry では Plug'n'Play（PnP）という新しい依存関係解決の仕組みや、ワークスペースの改善、プラグインシステムなどが導入されました。

以下の図は、Yarn のバージョン履歴と主な変更点を示しています。

mermaidCopy codeflowchart LR
  classic["Yarn Classic<br/>(v1.x)"] -->|2020年| berry["Yarn Berry<br/>(v2.x)"]
  berry -->|改善| v3["Yarn v3.x"]
  v3 -->|最新| v4["Yarn v4.x"]

  classic -.->|特徴| feature1["node_modules"]
  berry -.->|特徴| feature2["Plug'n'Play<br/>Zero-Install"]
  v3 -.->|特徴| feature3["パフォーマンス改善<br/>ESM サポート"]
  v4 -.->|特徴| feature4["hardened mode<br/>セキュリティ強化"]

このように、Yarn は段階的に進化を続けており、現在では v4 系が最新となっています。

Yarn Berry を採用する利点

Yarn Berry には、Classic にはない多くの利点があります。

Plug'n'Play（PnP）モードでは、node_modules ディレクトリを作成せず、依存関係の解決を高速化できます。これにより、インストール時間が大幅に短縮されるだけでなく、ディスク容量の節約にもつながるのです。

Zero-Install という機能を使えば、依存関係のキャッシュをリポジトリにコミットすることで、yarn install を実行せずにプロジェクトをすぐに実行できます。CI/CD 環境での高速化に特に効果的でしょう。

ワークスペースの改善により、モノレポ構成での開発がより快適になりました。依存関係の管理やビルドの最適化が、従来よりもスムーズに行えます。

さらに、プラグインシステムを活用すれば、TypeScript や Webpack との統合を強化したり、カスタム機能を追加したりできます。拡張性が高く、プロジェクトの要件に合わせた柔軟なカスタマイズが可能です。

課題

Classic から Berry への移行で直面する問題

Yarn Classic から Berry への移行は、単純にバージョンを上げるだけでは完了しません。いくつかの課題に直面する可能性があるのです。

Plug'n'Play（PnP）の互換性問題が最も大きな障壁でしょう。PnP モードでは node_modules が作成されないため、ファイルシステムから直接パッケージを読み込もうとするツールやライブラリが動作しない場合があります。

設定ファイルの変更も必要です。Yarn Berry では .yarnrc.yml という新しい設定ファイル形式が採用されており、Classic の .yarnrc とは互換性がありません。既存の設定を移行する作業が発生します。

スクリプトやツールチェーンの調整も避けられません。CI/CD パイプラインや Docker イメージ、IDE の設定など、Yarn を参照している箇所すべてを見直す必要があるでしょう。

以下の図は、移行時に確認すべき主な項目を示しています。

mermaidCopy codeflowchart TB
  start["移行開始"] --> check1["PnP 互換性確認"]
  check1 --> check2["設定ファイル移行"]
  check2 --> check3["スクリプト調整"]
  check3 --> check4["依存パッケージ更新"]
  check4 --> check5["CI/CD 設定変更"]
  check5 --> result["移行完了"]

  check1 -.->|問題| fallback1["node-modules モード検討"]
  check4 -.->|エラー| fallback2["パッケージ個別対応"]

これらの課題を一つずつ解決していくことで、スムーズな移行が実現できます。

バージョン指定の混乱

yarn set version コマンドには複数の指定方法があり、初めて使う方は混乱しやすいものです。

具体的なバージョン番号を指定する方法（例：yarn set version 3.6.0）、stable や berry といったエイリアスを使う方法、さらには URL を指定してカスタムビルドをダウンロードする方法など、選択肢が豊富すぎて迷ってしまうでしょう。

また、プロジェクトごとにバージョンを固定する仕組みについても理解が必要です。Yarn Berry では、プロジェクトルートに .yarn​/​releases ディレクトリが作成され、そこに Yarn 本体がダウンロードされます。この仕組みを理解していないと、グローバルにインストールした Yarn とプロジェクトローカルの Yarn が混在し、予期しない動作を引き起こす可能性があるのです。

解決策

yarn set version コマンドの基本

yarn set version コマンドは、プロジェクトで使用する Yarn のバージョンを設定する重要なコマンドです。このコマンドを実行すると、指定したバージョンの Yarn がプロジェクトローカルにダウンロードされます。

基本的な構文は以下の通りです。

bashCopy code# 特定のバージョンを指定
yarn set version <version>

# stable（安定版）を指定
yarn set version stable

# berry（最新の v2 以降）を指定
yarn set version berry

# 最新版を指定
yarn set version latest

このコマンドを実行すると、以下のような処理が行われます。

1. 指定したバージョンの Yarn がダウンロードされる
2. .yarn​/​releases ディレクトリに保存される
3. .yarnrc.yml に yarnPath が設定される
4. 以降、yarn コマンドはこのローカルバージョンを使用する

プロジェクトルートで実行することで、チーム全体で同じバージョンの Yarn を使用できるようになるのです。

バージョン指定のベストプラクティス

実際の移行では、どのバージョン指定方法を選ぶべきでしょうか。

推奨は stable を使用する方法です。yarn set version stable を実行すれば、その時点での最新安定版がダウンロードされます。これにより、安定性とモダンな機能のバランスが取れた環境を構築できるでしょう。

bashCopy code# 最も推奨される方法
yarn set version stable

具体的なバージョン番号を指定する方法は、特定のバージョンに固定したい場合に有効です。例えば、本番環境で動作確認済みのバージョンを使い続けたい場合などに適しています。

bashCopy code# 特定のバージョンに固定
yarn set version 3.6.0

berry を指定する方法は、Yarn Berry の最新版を常に使用したい場合に便利です。ただし、メジャーバージョンアップによる破壊的変更のリスクがあるため、注意が必要でしょう。

bashCopy code# Berry の最新版を使用（v2 以降）
yarn set version berry

以下の表で、各指定方法の特徴を比較してみました。

#	指定方法	安定性	最新機能	推奨度	用途
1	stable	★★★	★★★	★★★	通常のプロジェクト
2	具体的バージョン	★★★	★★☆	★★☆	本番環境・固定が必要な場合
3	berry	★★☆	★★★	★☆☆	実験的プロジェクト
4	latest	★☆☆	★★★	★☆☆	開発環境での試験

段階的な移行戦略

いきなり本番環境で移行を行うのはリスクが高いため、段階的なアプローチを取りましょう。

第 1 段階：開発環境での試験では、まず自分のローカル環境でテスト的に移行を実施します。ここで問題点を洗い出し、対処方法を検討します。

第 2 段階：node-modules モードでの移行では、PnP モードではなく、従来通り node_modules を使用するモードで移行します。これにより、互換性問題を最小限に抑えながら、Yarn Berry の他の機能を活用できるのです。

第 3 段階：PnP モードへの移行では、互換性の確認が完了したら、PnP モードを有効にします。これにより、Yarn Berry の最大のメリットを享受できるでしょう。

移行フローを図で示すと、以下のようになります。

mermaidCopy codestateDiagram-v2
  [*] --> LocalTest: ローカル環境でテスト
  LocalTest --> NodeModules: node-modules モードで移行
  NodeModules --> Verify: 動作確認
  Verify --> PnP: 問題なければ PnP 移行
  Verify --> Adjust: 問題あれば調整
  Adjust --> Verify: 再テスト
  PnP --> Production: 本番環境へデプロイ
  Production --> [*]

  note right of NodeModules
    互換性を保ちつつ移行
  end note

  note right of PnP
    最大の性能を発揮
  end note

この段階的アプローチにより、リスクを最小限に抑えながら移行を進められます。

具体例

実際の移行手順（ステップバイステップ）

それでは、実際にプロジェクトを Yarn Classic から Berry に移行する手順を、ステップごとに詳しく見ていきましょう。

ステップ 1：現在の環境確認

まず、現在使用している Yarn のバージョンを確認します。

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

出力例：

bashCopy code1.22.19

この出力が 1.x.x であれば、Yarn Classic を使用していることが確認できます。

次に、プロジェクトの依存関係を確認しておきましょう。

bashCopy code# package.json の内容を確認
cat package.json

特に devDependencies と dependencies に記載されているパッケージのうち、Yarn Berry で問題が起きやすいものをリストアップしておきます。

ステップ 2：バックアップの作成

移行前に、念のため現在の状態をバックアップしておくことをおすすめします。

bashCopy code# Git でコミット（変更がある場合）
git add .
git commit -m "chore: Yarn Classic の最終状態を保存"

# ブランチを作成
git checkout -b migrate-to-yarn-berry

これにより、何か問題が発生した場合でも、すぐに元の状態に戻せます。

ステップ 3：Yarn Berry への切り替え

いよいよ yarn set version コマンドを実行します。

bashCopy code# Yarn Berry の安定版に切り替え
yarn set version stable

このコマンドを実行すると、以下のような出力が表示されます。

bashCopy code➤ YN0000: Retrieving https://repo.yarnpkg.com/3.6.0/packages/yarnpkg-cli/bin/yarn.js
➤ YN0000: Saving the new release in .yarn/releases/yarn-3.6.0.cjs
➤ YN0000: Done in 0s 234ms

実行後、プロジェクトルートに以下のファイルとディレクトリが作成されます。

• .yarn​/​releases​/​yarn-3.6.0.cjs：Yarn Berry 本体
• .yarnrc.yml：Yarn Berry の設定ファイル

ステップ 4：設定ファイルの確認と調整

作成された .yarnrc.yml の内容を確認しましょう。

bashCopy code# .yarnrc.yml の内容を確認
cat .yarnrc.yml

初期状態では、以下のような内容になっています。

yamlCopy codeyarnPath: .yarn/releases/yarn-3.6.0.cjs

ここで、node-modules モードを使用する設定を追加します。これにより、PnP による互換性問題を回避できるのです。

yamlCopy code# .yarnrc.yml に以下を追加
yarnPath: .yarn/releases/yarn-3.6.0.cjs
nodeLinker: node-modules

nodeLinker: node-modules を設定することで、従来通り node_modules ディレクトリが作成されます。

ステップ 5：既存の依存関係を削除

古い node_modules と yarn.lock を削除します。

bashCopy code# node_modules を削除
rm -rf node_modules

# yarn.lock を削除（Berry で再生成されます）
rm yarn.lock

これらのファイルは、次のステップで Yarn Berry によって再生成されます。

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

Yarn Berry を使って依存関係を再インストールします。

bashCopy code# 依存関係をインストール
yarn install

このコマンドを実行すると、Yarn Berry が依存関係を解決し、新しい yarn.lock が作成されます。

出力例：

bashCopy code➤ YN0000: ┌ Resolution step
➤ YN0000: └ Completed in 2s 345ms
➤ YN0000: ┌ Fetch step
➤ YN0000: └ Completed in 1s 234ms
➤ YN0000: ┌ Link step
➤ YN0000: └ Completed in 0s 567ms
➤ YN0000: Done with warnings in 4s 146ms

エラーが表示される場合は、次のステップで対処します。

ステップ 7：動作確認

プロジェクトが正常に動作するか確認しましょう。

bashCopy code# ビルドコマンドを実行
yarn build

# テストを実行
yarn test

# 開発サーバーを起動
yarn dev

それぞれのコマンドが正常に完了すれば、基本的な移行は成功です。

ステップ 8：Git へのコミット

移行が完了したら、変更をコミットします。

bashCopy code# 新しいファイルを追加
git add .yarn .yarnrc.yml yarn.lock

# .gitignore の更新（必要に応じて）
echo ".yarn/cache" >> .gitignore
echo ".yarn/unplugged" >> .gitignore
echo ".yarn/build-state.yml" >> .gitignore
echo ".yarn/install-state.gz" >> .gitignore

# コミット
git add .gitignore
git commit -m "chore: Yarn Classic から Yarn Berry (v3.6.0) に移行"

.yarn​/​releases はコミットに含めることで、チーム全体で同じバージョンを使用できます。

よくあるエラーと対処法

移行時に遭遇しやすいエラーと、その解決方法をご紹介します。

エラー 1：Error: Cannot find module エラー

エラーコード: Error: Cannot find module 'パッケージ名'

エラーメッセージ:

bashCopy codeError: Cannot find module 'typescript'
Require stack:
- /path/to/project/script.js

発生条件: PnP モードで、パッケージを直接 require() しようとした場合に発生します。

解決方法:

1. nodeLinker: node-modules を .yarnrc.yml に設定する
2. または、PnP に対応させるために .pnp.cjs を require する

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

設定後、再インストールを実行します。

bashCopy codeyarn install

エラー 2：packageExtensions が必要な場合

エラーコード: YN0060: <パッケージ名> is listed by your project with version <バージョン>, which doesn't satisfy what <依存パッケージ> requests

エラーメッセージ:

bashCopy code➤ YN0060: package-a is listed by your project with version 1.0.0,
          which doesn't satisfy what package-b requests (^2.0.0)

発生条件: パッケージの peerDependencies が正しく解決できない場合に発生します。

解決方法:

.yarnrc.yml に packageExtensions を追加して、依存関係を手動で修正します。

yamlCopy code# .yarnrc.yml
packageExtensions:
  'package-a@*':
    peerDependencies:
      package-b: '*'

この設定により、Yarn が依存関係を正しく解決できるようになります。

エラー 3：スクリプト実行時のパスエラー

エラーコード: sh: command not found

エラーメッセージ:

bashCopy codesh: eslint: command not found
error Command failed with exit code 127.

発生条件: node_modules​/​.bin へのパスが通っていない場合に発生します。

解決方法:

1. yarn run を使ってスクリプトを実行する
2. または、package.json のスクリプトを修正する

jsonCopy code{
  "scripts": {
    "lint": "yarn eslint .",
    "format": "yarn prettier --write ."
  }
}

yarn コマンドを前置することで、正しいパスでコマンドが実行されます。

PnP モードへの移行（オプション）

node-modules モードで安定稼働が確認できたら、PnP モードへの移行を検討しましょう。PnP モードでは、インストール速度とディスク使用量が大幅に改善されます。

PnP モードの有効化

.yarnrc.yml から nodeLinker の設定を削除するか、pnp に変更します。

yamlCopy code# .yarnrc.yml
yarnPath: .yarn/releases/yarn-3.6.0.cjs
nodeLinker: pnp

または、nodeLinker 行を削除します（デフォルトが PnP）。

yamlCopy code# .yarnrc.yml
yarnPath: .yarn/releases/yarn-3.6.0.cjs

PnP モードでの再インストール

設定を変更したら、node_modules を削除して再インストールします。

bashCopy code# node_modules を削除
rm -rf node_modules

# PnP モードで再インストール
yarn install

実行後、.pnp.cjs というファイルが生成されます。これが PnP の依存関係マップです。

エディタの設定

VSCode などのエディタで PnP モードを認識させるために、SDK をインストールします。

bashCopy code# VSCode 用の SDK をインストール
yarn dlx @yarnpkg/sdks vscode

このコマンドを実行すると、.yarn​/​sdks ディレクトリが作成され、エディタが PnP を正しく認識できるようになります。

実行後の出力例：

bashCopy code➤ YN0000: ┌ Resolution step
➤ YN0000: └ Completed
➤ YN0000: ┌ Fetch step
➤ YN0000: └ Completed
➤ YN0000: ┌ Link step
➤ YN0000: │ ESM support for PnP uses the experimental loader API and is therefore experimental
➤ YN0000: └ Completed
➤ YN0000: Successfully created SDKs for VSCode

VSCode を再起動すれば、TypeScript や ESLint などが PnP 環境で正しく動作します。

CI/CD 環境での設定

最後に、CI/CD 環境での Yarn Berry の使用方法を確認しましょう。

GitHub Actions の例

.github​/​workflows​/​ci.yml の設定例です。

yamlCopy codename: CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

次に、ジョブの定義を追加します。

yamlCopy codejobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v4

Node.js のセットアップでは、Corepack を有効にします。

yamlCopy code- name: Setup Node.js
  uses: actions/setup-node@v4
  with:
    node-version: '20'
    cache: 'yarn'

Corepack を有効にして、Yarn Berry を使用可能にします。

yamlCopy code- name: Enable Corepack
  run: corepack enable

依存関係をインストールし、テストを実行します。

yamlCopy code- name: Install dependencies
  run: yarn install --immutable

- name: Run tests
  run: yarn test

- name: Build
  run: yarn build

--immutable フラグを付けることで、yarn.lock が変更されないことを保証できます。

Docker での使用

Dockerfile の例です。

dockerfileCopy codeFROM node:20-alpine

# Corepack を有効化
RUN corepack enable

作業ディレクトリを設定し、必要なファイルをコピーします。

dockerfileCopy codeWORKDIR /app

# package.json と yarn の設定をコピー
COPY package.json yarn.lock .yarnrc.yml ./
COPY .yarn ./.yarn

依存関係をインストールします。

dockerfileCopy code# 依存関係をインストール
RUN yarn install --immutable

残りのファイルをコピーして、ビルドを実行します。

dockerfileCopy code# ソースコードをコピー
COPY . .

# ビルド
RUN yarn build

# アプリケーションを起動
CMD ["yarn", "start"]

この Dockerfile により、Yarn Berry を使った Docker イメージを構築できます。

まとめ

本記事では、Yarn Classic から Yarn Berry への移行手順を、yarn set version コマンドを中心に解説いたしました。

移行の重要なポイントをまとめると、以下の通りです。

まず、段階的なアプローチを取ることが成功の鍵です。いきなり PnP モードに移行するのではなく、まず node-modules モードで動作確認を行い、問題がないことを確認してから PnP に移行しましょう。

次に、yarn set version stable を使用することで、安定版の Yarn Berry を簡単に導入できます。このコマンド一つで、プロジェクトローカルに Yarn がインストールされ、チーム全体で同じバージョンを共有できるのです。

そして、.yarnrc.yml で適切な設定を行うことが重要です。特に、最初は nodeLinker: node-modules を設定することで、互換性問題を回避しながら移行を進められます。

さらに、CI/CD 環境での対応も忘れずに行いましょう。Corepack を有効にし、--immutable フラグを使用することで、安定した自動化環境を構築できます。

最後に、エラーが発生した場合も慌てずに対処しましょう。本記事で紹介したエラー対処法を参考に、一つずつ問題を解決していけば、必ず移行を完了できます。

Yarn Berry への移行は、最初は戸惑うかもしれませんが、移行後はパッケージ管理の効率が大幅に向上し、開発体験が改善されるでしょう。ぜひ本記事を参考に、安全かつスムーズな移行を実現してください。

関連リンク

• Yarn 公式サイト
• Yarn Berry（v2+）公式ドキュメント
• Yarn Migration Guide
• Plug'n'Play の仕組み
• Corepack 公式ドキュメント
• Yarn GitHub リポジトリ
• packageExtensions の使い方