GitHub Codespacesでnpmからpnpmへ移行する

概要

このブログの開発環境であるGitHub Codespacesで、パッケージマネージャをデフォルトで設定されているnpmからpnpmに移行しました。

pnpmは、高速なインストール速度とディスク容量の効率的な使用が特徴のパッケージマネージャです。GitHub Codespacesでは、Corepackによる自動セットアップとdevcontainer.jsonの設定だけで、スムーズに移行できます。

この記事では、実際に行った設定変更と移行手順について、具体的な変更箇所をメモとして残しておきます。この記事はGitHub Codespacesを使用している環境を前提としています。DevContainerの基本については、別記事「DevContainerの基礎知識：開発環境をコードで定義する」を参照してください。

pnpmの特徴と選択理由

pnpm（performant npm）は、npmやYarnの代替となる高速で効率的なパッケージマネージャです。

pnpmには次のような特徴があります。

• npmと比較して2〜3倍高速な依存関係のインストール
• パッケージをグローバルストアに保存し、プロジェクトごとにハードリンクを作成するため、ディスク容量を節約
• package.jsonに明示的に記載されていない依存関係へのアクセスを防ぎ、依存関係の問題を早期発見
• ワークスペース機能により、monorepoなど複数パッケージを含むリポジトリの管理が容易

このプロジェクトでは、ビルド時間の短縮とCI環境でのディスク使用量削減を目的にpnpmを採用しました。

移行手順

npmからpnpmへの移行には、5つのステップが必要です。

1. package.jsonにパッケージマネージャのバージョンを明示
2. Codespaces用のdevcontainer.json設定ファイル作成
3. npm関連ファイルの削除と依存関係の再インストール
4. 既存環境での動作確認
5. 新規Codespacesでの自動セットアップ確認

それぞれの手順を詳しく見ていきます。

1. package.jsonの設定

packageManagerフィールドを追加して、使用するpnpmのバージョンを明示します。

{
  "name": "your-project",
  "version": "1.0.0",
  "packageManager": "pnpm@10.23.0",
  "scripts": {
    ...
  }
}

このフィールドにより、Node.jsのCorepackが自動的に指定バージョンのpnpmを使用します。

2. devcontainer.jsonの設定

GitHub Codespacesでは、.devcontainer/devcontainer.jsonを設定してpnpmを自動セットアップします。

{
  "name": "your-project",
  "postCreateCommand": "pnpm install",
  "customizations": {
    "vscode": {
      "settings": {
        "npm.packageManager": "pnpm"
      },
      "extensions": [
        "dbaeumer.vscode-eslint",
        "biomejs.biome"
      ]
    }
  },
  "forwardPorts": [3000]
}

これらの設定で、Codespacesの起動時にCorepackが自動的にpnpmをインストールし、postCreateCommandで依存関係がインストールされます。

3. npm関連ファイルの削除と依存関係の再インストール

既存のnode_modulesとpackage-lock.jsonを削除し、pnpmで依存関係を再インストールします。

rm -rf node_modules package-lock.json
pnpm install

インストール実行後、pnpm-lock.yamlが生成されます。

4. 既存環境での動作確認

開発サーバーを起動して、移行が正しく完了したことを確認します。

pnpm run dev

問題なく起動したら、型チェックとビルドを実行します。

# 型チェック
pnpm run type-check

# ビルド
pnpm run build

もし型定義に関するエラーが発生した場合、pnpmの厳格な依存管理が原因の可能性があります。npmでは暗黙的に利用できていたパッケージも、pnpmでは明示的なインストールが必要です。エラーメッセージに従って必要なパッケージを追加インストールしてください。

# 例: 型定義が見つからない場合
pnpm add -D @types/パッケージ名

5. 新規Codespacesでの自動セットアップ確認

動作確認が完了したら、変更した設定ファイルをコミットします。Codespacesの管理画面から新しいCodespacesを作成し、自動セットアップが正しく動作するか確認してください。

問題なくビルドが完了し、開発サーバーが起動すれば、移行は成功です。

まとめ

GitHub Codespacesでnpmからpnpmへの移行を実施しました。Corepackによる自動セットアップにより、package.jsonとdevcontainer.jsonの設定のみで移行が完了します。

pnpmの導入により、依存関係のインストール時間が短縮され、ディスク使用量も削減されました。厳格な依存管理により、暗黙的な依存関係の問題も早期に発見できます。

既存のCodespaces環境でパッケージマネージャの変更を検討している場合、この手順を参考に移行を進めてください。