GitHub Codespacesでnpmからpnpmへパッケージマネージャを移行する

概要

このブログの開発環境であるGitHub Codespacesで、パッケージマネージャをデフォルトで設定されているnpmからpnpmに移行したので、具体的な変更箇所についてメモを残しておきます。

前提条件

GitHub Codespacesをデフォルトで使用している前提で解説します。
DevContainerとGitHub Codespacesの基本的な仕組みについては、別記事「DevContainerの基礎知識：開発環境をコードで定義する」を参照してください。

pnpmとは

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

pnpmの特徴

• 高速なインストール速度
• ディスク容量の効率的な使用
• 厳格な依存関係管理
• monorepo対応のワークスペース機能

移行手順

npmからpnpmへの移行では、以下の作業を行います。

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]
}

package.jsonのpackageManagerフィールドが設定されていれば、Node.jsが自動的に指定バージョンのpnpmを使用します。

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 add -D @types/パッケージ名

5. 新しいCodespacesをビルド

動作確認が完了したら、変更した設定ファイルをコミットします。Codespacesの管理画面から新しいCodespacesを作成し、問題なく動作するか確認しましょう。

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