volta pin

プロジェクトのツールチェーンを固定し、package.jsonに記録します。

使用法

volta pin [オプション] <ツール[@バージョン]>

引数

<ツール[@バージョン]>

固定するツール。以下の形式のいずれかを指定できます：

• node - 現在のデフォルトNodeバージョンを固定
• node@version - 特定のNodeバージョンを固定
• npm - 現在のデフォルトnpmバージョンを固定
• npm@version - 特定のnpmバージョンを固定
• yarn - 現在のデフォルトYarnバージョンを固定
• yarn@version - 特定のYarnバージョンを固定
• pnpm - 現在のデフォルトpnpmバージョンを固定（pnpmサポートが有効な場合）
• pnpm@version - 特定のpnpmバージョンを固定

オプション

--verbose

詳細な出力を有効にします。

--quiet

不要な出力を抑制します。

--help

このコマンドのヘルプ情報を表示します。

動作

package.json への記録

volta pinは、現在のディレクトリまたは最も近い親ディレクトリのpackage.jsonファイルのvoltaセクションにツールバージョンを記録します：

{
  "name": "my-project",
  "version": "1.0.0",
  "volta": {
    "node": "18.17.0",
    "npm": "9.8.0"
  }
}

自動インストール

指定されたツールバージョンがまだインストールされていない場合、Voltaは自動的にそれをインストールします。

プロジェクトスコープ

固定されたバージョンは、そのプロジェクトディレクトリ内でのみ有効です。他のプロジェクトのデフォルトツールには影響しません。

例

基本的な使用法

# 現在のNodeバージョンを固定
volta pin node

# 特定のNodeバージョンを固定
volta pin node@18.17.0

# npmバージョンを固定
volta pin npm@9.8.0

# 複数のツールを固定
volta pin node@16.14.2 npm@8.19.4

パッケージマネージャーの固定

# Yarnを固定
volta pin yarn@1.22.19

# pnpmを固定（pnpmサポートが有効な場合）
volta pin pnpm@7.33.6

# 特定のnpmバージョンを固定
volta pin npm@8.5.0

バージョン形式

# 正確なバージョン
volta pin node@18.17.0

# メジャーバージョンのみ
volta pin node@18

# latestタグ
volta pin node@latest

# LTSバージョン
volta pin node@lts

実践的な例

新しいプロジェクトのセットアップ

# プロジェクトディレクトリを作成
mkdir my-new-project
cd my-new-project

# package.jsonを初期化
npm init -y

# ツールチェーンを固定
volta pin node@18.17.0 npm@9.8.0

# 確認
cat package.json

既存プロジェクトでのツール更新

# 現在の設定を確認
cat package.json | grep volta

# Nodeを新しいバージョンに更新
volta pin node@20.5.0

# npmも更新
volta pin npm@9.8.0

# 変更を確認
git diff package.json

チーム開発でのツール統一

# チームで使用するツールバージョンを統一
volta pin node@18.17.0
volta pin npm@9.8.0
volta pin yarn@1.22.19

# package.jsonをコミット
git add package.json
git commit -m "Pin Node.js and package manager versions"

ワークスペースでの使用

モノレポでの固定

# ルートディレクトリでツールを固定
volta pin node@18.17.0 npm@9.8.0

# 特定のパッケージで異なるバージョンを固定
cd packages/legacy-app
volta pin node@16.14.2 npm@8.19.4

cd ../../apps/new-app
volta pin node@20.5.0 npm@10.0.0

共有設定の使用

# 共有設定ファイルを参照
volta pin node@18.17.0

# package.jsonで共有設定を拡張
{
  "volta": {
    "extends": "../shared-volta-config.json",
    "npm": "9.8.0"
  }
}

CI/CDでの活用

GitHub Actions

name: Test
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Install Volta
        run: |
          curl https://get.volta.sh | bash
          echo "$HOME/.volta/bin" >> $GITHUB_PATH
      
      # package.jsonで固定されたバージョンが自動的に使用される
      - name: Install dependencies
        run: npm ci
      
      - name: Run tests
        run: npm test

Docker

FROM node:18

# Voltaをインストール
RUN curl https://get.volta.sh | bash
ENV PATH="/root/.volta/bin:$PATH"

WORKDIR /app
COPY package.json ./

# package.jsonの設定に基づいてツールが自動選択される
RUN npm ci

COPY . .
RUN npm run build

トラブルシューティング

package.jsonが見つからない場合

volta pin node@18.17.0
# エラー: No package.json found in current directory or any parent directory

解決方法：

# package.jsonを作成
npm init -y

# 再度実行
volta pin node@18.17.0

権限エラー

volta pin node@18.17.0
# エラー: Permission denied

解決方法：

# ファイルの権限を確認
ls -la package.json

# 必要に応じて権限を修正
chmod 644 package.json

バージョンの競合

# 既存の設定を確認
cat package.json | grep volta

# 特定のバージョンを強制的に上書き
volta pin node@20.5.0 --verbose

ベストプラクティス

1. 一貫したバージョニング

# チーム全体で同じバージョンを使用
volta pin node@18.17.0 npm@9.8.0

# セマンティックバージョニングに従う
volta pin node@18.17.0  # パッチバージョンまで指定

2. 定期的な更新

# 定期的にツールを更新
volta pin node@latest
volta pin npm@latest

# セキュリティアップデートをチェック
npm audit

3. 文書化

## 開発環境セットアップ

このプロジェクトでは以下のツールバージョンを使用します：

- Node.js: 18.17.0
- npm: 9.8.0

Voltaを使用している場合、プロジェクトディレクトリで自動的に適切なバージョンが選択されます。

関連コマンド

• volta install - ツールをインストール
• volta list - インストールされているツールを確認
• volta which - 現在使用されているツールのパスを確認
• volta run - 特定のツールバージョンでコマンドを実行