パッケージマネージャーをYarnからnpmに移行

ActiveAdminはJavaScriptパッケージマネージャーをYarnからnpmに統一しました。CI/CDパイプライン、リリーススクリプト、開発環境セットアップ手順など、プロジェクト全体にわたる変更です。

背景

これまでActiveAdminはYarnをJavaScriptパッケージマネージャーとして採用しており、yarn.lockによって依存関係が管理されていました。一方でnpmもpackage-lock.jsonによる同等のロック機能を提供しており、Node.jsに標準バンドルされているため、追加インストールが不要という利点があります。

今回の移行により、yarn.lock（2077行削除）が削除され、新たにpackage-lock.json（4075行追加）が導入されました。ツールチェーンを標準のnpmに絞ることで、開発環境のセットアップに必要なツール数が削減されます。

技術的な変更

Yarnコマンドはプロジェクト全体でnpmの対応コマンドに置き換えられました。主な対応関係は次のとおりです。

Yarn（変更前）	npm（変更後）
yarn install	npm install
yarn install --frozen-lockfile --immutable	npm ci
yarn build	npm run build
yarn docs:build	npm run docs:build
yarn gherkin-lint	npm run gherkin-lint
yarn add @activeadmin/activeadmin	npm install @activeadmin/activeadmin

CI/CDワークフローでは、actions/setup-node の cache オプションが yarn から npm に変更されています。また、yarn.lock を変更検知対象のファイルリストから除外し、代わりに package-lock.json の変更で各ジョブがトリガーされるようになります（package*.json のグロブで対応済み）。

# 変更前
- uses: actions/setup-node@v6.4.0
  with:
    node-version: 24
    cache: yarn
- run: yarn install
- run: yarn docs:build

# 変更後
- uses: actions/setup-node@v6.4.0
  with:
    node-version: 24
    cache: npm
- run: npm ci
- run: npm run docs:build

bin/prep-release スクリプトでは、依存関係のクリーンインストールに yarn install --frozen-lockfile の代わりに npm ci が使われるようになりました。npm ci はロックファイルを厳格に参照して冪等なインストールを行うコマンドであり、CI・リリース用途での動作は従来と同等です。

# 変更前
system "yarn install --frozen-lockfile"
system "yarn build"

# 変更後
system "npm ci"
system "npm run build"

tasks/test_application.rb では、テストアプリ生成時の依存インストールおよびCSSビルドがすべてnpmコマンドに統一されています。

設計判断

package*.json グロブによる変更検知の維持という設計が継続されています。package.json と package-lock.json の両方を一括で検知できるため、ロックファイルが yarn.lock から package-lock.json に変わっても、ワークフローのトリガー条件を大きく書き換える必要がありませんでした。

また、クリーンインストールが必要な場面（CI・リリーススクリプト）では npm ci を、開発用途では npm install を使い分けている点も注目です。Yarnの --frozen-lockfile フラグに相当する厳格性を npm ci で代替することで、再現性の高いビルドが保たれています。

まとめ

Yarnからnpmへの移行は機能的な変更を伴わないツールの統一ですが、Node.jsに標準付属するnpmに一本化することで、開発環境のセットアップ要件がシンプルになります。npm ci による厳格なロックファイル準拠と package*.json グロブを活用した変更検知の設計は、移行後も再現性と一貫性を維持しています。