Yarn 2 への移行
この記事の英語版に更新があります。ご覧の翻訳には含まれていない変更点があるかもしれません。
最終更新日 2022年02月14日(月)
Table of Contents
喜ばしいことに、Yarn 2 は 2020 年の初頭にリリースされました。チームでは、"ゼロインストール" のパッケージマネージャーを作成しました。つまり、ユーザーは “vendor” ディレクトリを使用して、自分の Yarn バイナリ、依存関係、開発の依存関係を自分のリポジトリに含めることができます。Yarn の新しい哲学についてはこちらをご覧ください。
この記事の目的は、現在の Heroku ユーザーが Yarn 1 から Yarn 2 に移行するのを支援することです。移行するアプリで Yarn 1 をすでに使用していること、また Heroku Node.js buildpack の最新バージョンを使用していることが前提です。この記事の内容は、Heroku Ruby buildpack などの他のスクリプトから Yarn をインストールするアプリケーションには当てはまりません。"ゼロダウンロード" の利点を最大限に活かすために、Heroku では、すべての依存関係を .yarn
ディレクトリに含めることが期待されています。
Yarn を使用している Heroku ユーザーが Yarn 2 に移行することは必須ではなく、Yarn 1 が非推奨になった後もユーザーはアプリ内で Yarn 1 にアクセスできます。しかし、パッケージマネージャーで最新のバグ修正とセキュリティパッチを確実にするために、Yarn 2 に移行することをお勧めします。
この記事を参考にして、アプリのコードをローカルで Yarn 2 に移行し、Heroku 上のアプリケーションも移行します。
以下の記述では、git
へのファイルのチェックインに言及していますが、指示内容は他のバージョン管理システムにも適用できます。
ローカルの設定
ローカル環境の準備
移行が必要なソースコードのディレクトリに移動します。ローカルコマンドはプロジェクトのルートで実行されます。ローカルの yarn バージョンが最新であることを確認してください。ローカルで更新するには、npm を使用してインストールを実行します。
npm install -g yarn
バージョンは 1.22.4 以上である必要があります。>= 1.22.4
確認するには yarn -v
を実行します。
カスタムのキャッシュディレクトリをワークスペースに移動する
package.json
に cacheDirectories
セクションがない場合は、次のセクションに進んでください。
package.json
で、cacheDirectories
を workspaces
に変更します。たとえば、次の内容があるとします。
"cacheDirectories": [
"client/node_modules"
]
これを次のように変更し、プロジェクトが非公開であることを指定します。
"workspaces": [
"client"
],
"private": true,
node_modules
ディレクトリを指定する必要はありません。サブディレクトリの package.json
内の "name"
キーが、ルートの package.json
で指定されたディレクトリ名とワークスペース名を反映していることを確認してください。
次に、サブディレクトリに node_modules
フォルダーと yarn.lock
ファイルがあれば削除し、アプリケーションディレクトリに移動して yarn
を実行します。
cd ~/path/to/project && yarn install
ディレクトリの yarn.lock
ファイルが更新され、ワークスペースによって指定された依存関係ツリー全体が反映されます。サブディレクトリの package.json
で指定された依存関係を探して、ロックファイルが更新されたことを確認してください。
ソースコードの変更
Heroku で Yarn 2 を使用するために、Git にチェックインする必要がある追加のファイルが存在します。Yarn は “ゼロダウンロード” の哲学に傾倒しています。多くのファイルとディレクトリを Git にチェックインするための追加のダウンロードコストが発生しますが、これによって高速なビルドが Heroku で作成されます。
yarn
を使用して、ソースコードに yarn のバージョンを設定します。
yarn set version berry
ゼロインストール機能を使用するには (これにより、ローカルでキャッシュされた依存関係が Heroku にプッシュされます)、.gitginore
に次を追加します。
.yarn/*
!.yarn/cache
!.yarn/releases
!.yarn/plugins
!.yarn/sdks
!.yarn/versions
代わりにゼロインストール機能からオプトアウトするには (これにより、すべての依存関係をダウンロードしてインストールするよう buildpack がトリガーされます)、.gitignore
に次を追加します。
.pnp.*
.yarn/*
!.yarn/patches
!.yarn/plugins
!.yarn/releases
!.yarn/sdks
!.yarn/versions
次に、Yarn を使用してパッケージをインストールし、必要なファイルを作成します。
yarn install
これにより、.yarnrc.yml
ファイル、.yarn
ディレクトリ、pnp.js
ファイルが作成され、yarn.lock
が変更されます。これらを Git にチェックインし、ビルド時に Heroku で使用できることを確認します。
.yarn/cache
の内容は node_modules
と比較できません。これらのファイルは圧縮され、プロジェクトへのチェックインが意図されています。
Heroku アプリのキャッシュのクリア
Heroku では、ビルドの開始時にキャッシュが復元されることも、ビルドの終了時にキャッシュが保存されることもないため、以前のビルドから残っているビルドキャッシュを前もってパージすることができます。
heroku-cli
がインストールされていることを確認してください。その後、heroku-builds
プラグインをインストールします。
heroku plugins:install heroku-builds
次に、コマンドを実行してキャッシュをクリアします。
heroku builds:cache:purge --app $APP_NAME
この後、アプリを再デプロイする必要がありますが、その前に、デプロイを確実に成功させるために次の手順を完了してください。
Heroku 環境の更新 (Plug'n'Play を使用)
Yarn 2 を使用している場合、Yarn の Plug'n'Play を使用して依存関係を参照するか、ノードモジュールを使用し続けるかを選択できます。それぞれの場合で少し異なった設定が必要なため、ノードモジュールを使用する場合は、それに応じたアプリの設定を行ってください。
依存関係キャッシュの無効化
Heroku では現在、Yarn 2 との依存関係を .yarn/cache
ディレクトリからキャッシュしません。Plug'n'Play を使用する場合、Yarn は zip 圧縮された依存関係が .yarn/cache
ディレクトリにあることを期待します。ただしその場合でも、すべての依存関係に対して postinstall
スクリプトが実行されることを保証するために、buildpack は yarn install
を実行します。
Yarn 1 と node_modules
に関連付けられた環境変数を削除することが必要になります。したがって、NODE_MODULES_CACHE
環境変数を削除します。この変数を false
に設定する必要があります。
heroku config:set NODE_MODULES_CACHE=false
Heroku では .yarn/cache
ディレクトリからのキャッシングに取り組んでいますが、まだサポートされていません。カスタムキャッシュ設定を使用したい場合、カスタムキャッシング設定によって実現できます。
プライベートレジストリ環境変数の削除
プライベートレジストリにアクセスするためのトークンを設定済みであり、チェックインしたキャッシュと共に Yarn 2 を使用している場合は、トークンも設定解除してください。次のように実行できます。
heroku config:unset PRIVATE_NPM_TOKEN
Heroku 環境の更新 (ノードモジュール向け)
すでに述べたように、依存関係には Plug'n'Play またはノードモジュールのどちらかを使用します。Plug'n'Play を使用するには、前に説明した手順に従う必要があります。
Yarn 設定のセットアップ
依存関係に PnP を使用しないことを選択した場合、.yarnrc.yml
でこれを指定する必要があります。次の内容を追加します。
nodeLinker: "node-modules"
よりカスタマイズのしやすい Yarn 2 設定についてはこちらで説明されています。
これで、Yarn 2 でノードモジュールを使用する準備ができました。
devDependencies のプルーニング
Yarn 2 パッケージマネージャーはモジュール化されているため、devDependencies をプルーニングするためにワークスペースプラグインをインストールする必要があります。これが推奨されるのは、Node.js ランタイムでは devDependencies のインストールが不要なためで、したがってビルドの完了後にこれらを削除して、slug にコンパイルされないようにすることをお勧めします。
インストールするには、以下を実行します。
yarn plugin import workspaces-tools
Yarn を使用するために生成された他のファイルと一緒に、作成されたすべての成果物を .yarn ファイルで git にチェックインします。
アプリのテスト
変更が終わったら、必ずアプリのコードに対してテストスイートを実行してください。問題なくテストに合格したら、アプリケーションを Heroku にデプロイします。ビルドが成功したことを確認します。
問題が発生した場合は、GitHub で問題をオープンしてください。