npm/yarnコマンドリファレンス - パッケージ管理の早見表

Node.jsのパッケージ管理ツールであるnpmとyarnの実務でよく使うコマンドをまとめたリファレンス。対応するコマンドを並記しているため、両ツール間の読み替えにも使える。

npm と yarn の違い

項目	npm	yarn (v1 Classic)	yarn (v2+ Berry)
同梱	Node.jsに標準付属	別途インストール	`corepack enable` で有効化
lockファイル	`package-lock.json`	`yarn.lock`	`yarn.lock`
実行コマンド	`npx`	`yarn dlx`（v2+）	`yarn dlx`
ワークスペース	v7+ で対応	v1から対応	強化されたワークスペース
速度	v7以降で大幅改善	npm v6以前より高速	PnPモードで最速

プロジェクトの初期化

# 対話形式で package.json を作成
npm init
yarn init

# デフォルト値で即座に作成（質問なし）
npm init -y
yarn init -y

# スコープ付きパッケージとして初期化
npm init --scope=@myorg
yarn init  # package.json の name を手動で @myorg/pkg にする

パッケージのインストール

全依存関係のインストール

# package.json に基づいて全パッケージをインストール
npm install
yarn install    # または単に yarn

# CI環境向け（lockファイルに厳密に従う、package.jsonを書き換えない）
npm ci
yarn install --frozen-lockfile    # yarn v1
yarn install --immutable          # yarn v2+

# 本番依存のみインストール（devDependenciesを除外）
npm install --production
yarn install --production

個別パッケージのインストール

# dependencies に追加
npm install lodash
yarn add lodash

# devDependencies に追加
npm install -D typescript
yarn add -D typescript

# バージョン指定
npm install react@18.2.0         # 完全一致
npm install react@^18.0.0        # 互換バージョン
yarn add react@18.2.0
yarn add react@^18.0.0

# タグ指定
npm install next@latest
npm install next@canary
yarn add next@latest

# グローバルインストール
npm install -g typescript
yarn global add typescript       # yarn v1

インストールオプション

オプション	npm	yarn
dependencies に追加	`npm install <pkg>`	`yarn add <pkg>`
devDependencies に追加	`npm install -D <pkg>`	`yarn add -D <pkg>`
完全一致バージョンで追加	`npm install -E <pkg>`	`yarn add -E <pkg>`
グローバルインストール	`npm install -g <pkg>`	`yarn global add <pkg>`
optionalDependencies に追加	`npm install -O <pkg>`	`yarn add -O <pkg>`
peerDependencies に追加	手動で編集	`yarn add -P <pkg>`（v1）

パッケージの削除

# dependencies / devDependencies から削除
npm uninstall lodash
yarn remove lodash

# グローバルパッケージの削除
npm uninstall -g typescript
yarn global remove typescript    # yarn v1

npm uninstall は npm remove, npm rm, npm un でも同じ。

パッケージの更新

# 全パッケージを semver 範囲内で更新
npm update
yarn upgrade

# 特定パッケージを更新
npm update lodash
yarn upgrade lodash

# semver 範囲を無視して最新版に更新
npm install lodash@latest
yarn upgrade lodash --latest     # yarn v1

# 対話的にアップグレード対象を選択（yarn v1）
yarn upgrade-interactive
yarn upgrade-interactive --latest

更新可能なパッケージの確認

# outdated な依存関係を一覧表示
npm outdated
yarn outdated

出力例（npm）:

Package  Current  Wanted  Latest  Location
lodash   4.17.20  4.17.21 4.17.21 node_modules/lodash
react    18.2.0   18.2.0  18.3.1  node_modules/react

Current: 現在インストール済みのバージョン
Wanted: package.json の semver 範囲内で最新のバージョン
Latest: レジストリ上の最新バージョン

scripts の実行

# package.json の scripts を実行
npm run build
yarn build          # yarn は run を省略可能
yarn run build      # これも可

# 引数の渡し方
npm run test -- --watch
yarn test --watch   # yarn v1 は -- 不要

# scripts の一覧表示
npm run             # 引数なしで一覧
yarn run            # yarn v1

よく使われる scripts 規約

script名	用途
`start`	アプリケーションの起動
`dev`	開発サーバーの起動
`build`	プロダクションビルド
`test`	テスト実行
`lint`	リンター実行
`format`	フォーマッター実行
`preview`	ビルド結果のプレビュー
`prepare`	`npm install` 後に自動実行（huskyの設定等）

start, test などライフサイクルスクリプトは run を省略できる。

npm start       # npm run start と同じ
npm test        # npm run test と同じ

npx / yarn dlx

パッケージをインストールせずに一時的に実行する。

# npm
npx create-react-app my-app
npx -p typescript tsc --init       # パッケージ名と実行コマンドが異なる場合

# yarn v1
npx create-react-app my-app       # yarn v1 では npx を使用

# yarn v2+
yarn dlx create-react-app my-app

npx の主要オプション

npx <pkg>               # ローカル → グローバル → 一時DL の順で探して実行
npx -p <pkg> <cmd>      # パッケージ指定と実行コマンドを分離
npx --yes <pkg>         # 確認プロンプトをスキップ
npx --no <pkg>          # ローカルにない場合はエラー（DLしない）

パッケージ情報の確認

# パッケージ情報を表示
npm info react
yarn info react

# 特定フィールドのみ表示
npm info react version
npm info react versions         # 全バージョン一覧

# インストール済みパッケージの一覧
npm list
yarn list

# トップレベルのみ表示
npm list --depth=0
yarn list --depth=0

# グローバルパッケージの一覧
npm list -g --depth=0
yarn global list                # yarn v1

バージョン管理と公開

バージョンの更新

# semver に従ってバージョンを更新（package.json を書き換え＋git tag）
npm version patch       # 1.0.0 → 1.0.1
npm version minor       # 1.0.0 → 1.1.0
npm version major       # 1.0.0 → 2.0.0

# プレリリースバージョン
npm version prerelease  # 1.0.0 → 1.0.1-0
npm version prepatch    # 1.0.0 → 1.0.1-0
npm version preminor    # 1.0.0 → 1.1.0-0
npm version premajor    # 1.0.0 → 2.0.0-0

# git tag を作らない
npm version patch --no-git-tag-version

# yarn でも同様
yarn version --patch
yarn version --minor
yarn version --major

npm publish（パッケージの公開）

# npm レジストリにログイン
npm login
npm whoami              # ログイン中のユーザー確認

# 公開（public）
npm publish
npm publish --access public    # スコープ付きパッケージを公開する場合は必須

# ドライラン（実際には公開しない）
npm publish --dry-run

# タグ付き公開
npm publish --tag beta
npm publish --tag next

# 公開の取り消し（72時間以内のみ）
npm unpublish <pkg>@<version>

# 非推奨にする
npm deprecate <pkg>@<version> "メッセージ"

.npmignore と files フィールド

公開時に含めるファイルを制御する方法は2つある。

// package.json の files フィールド（ホワイトリスト方式、推奨）
{
  "files": ["dist", "README.md", "LICENSE"]
}

# .npmignore（ブラックリスト方式）
src/
tests/
*.test.js
.env

files フィールドが優先される。両方ある場合は files のみ有効。

公開前の確認

# 公開されるファイルの確認
npm pack --dry-run

# tarball を作成して中身を確認
npm pack
tar -tzf <package-name>-<version>.tgz

lockファイル

役割

lockファイルはインストールされた正確なバージョンを記録し、環境間で同一の依存ツリーを再現する。

パッケージマネージャー	lockファイル
npm	`package-lock.json`
yarn v1	`yarn.lock`
yarn v2+	`yarn.lock`（形式が異なる）
pnpm	`pnpm-lock.yaml`

運用ルール

lockファイルは必ずバージョン管理に含める（.gitignore に入れない）
手動で編集しない
コンフリクトが起きたら npm install / yarn install を再実行して解消する
CI環境では npm ci / yarn install --frozen-lockfile を使う

キャッシュ管理

# キャッシュの確認
npm cache ls              # npm v6以前
npm cache verify          # キャッシュの整合性を検証

# キャッシュのクリア
npm cache clean --force
yarn cache clean

# キャッシュディレクトリの確認
npm config get cache
yarn cache dir            # yarn v1

設定の管理

# 現在の設定を一覧
npm config list
npm config list -l         # デフォルト値も含めて全て表示
yarn config list           # yarn v1

# 個別の設定値を取得
npm config get registry
yarn config get registry

# 設定の変更
npm config set registry https://registry.npmmirror.com
yarn config set registry https://registry.npmmirror.com

# .npmrc ファイル（プロジェクトルートに配置可能）
# registry=https://registry.npmjs.org/
# save-exact=true
# engine-strict=true

.npmrc の配置場所と優先順位

プロジェクトルートの .npmrc（最優先）
ユーザーの ~/.npmrc
グローバルの $PREFIX/etc/npmrc
npmビルトインの /path/to/npm/npmrc

ワークスペース（monorepo）

npm workspaces（v7+）

// ルートの package.json
{
  "name": "my-monorepo",
  "private": true,
  "workspaces": ["packages/*"]
}

# 全ワークスペースで install
npm install

# 特定ワークスペースにパッケージを追加
npm install lodash -w packages/app

# 特定ワークスペースで scripts 実行
npm run build -w packages/app

# 全ワークスペースで scripts 実行
npm run build --workspaces
npm run build -ws

# 全ワークスペースでテスト（エラーがあっても続行）
npm run test -ws --if-present

yarn workspaces

// ルートの package.json（yarn v1）
{
  "private": true,
  "workspaces": ["packages/*"]
}

# 全ワークスペースで install
yarn install

# 特定ワークスペースにパッケージを追加
yarn workspace @myorg/app add lodash

# 特定ワークスペースで scripts 実行
yarn workspace @myorg/app run build

# 全ワークスペースで scripts 実行（yarn v1 plugin / yarn v2+）
yarn workspaces foreach run build       # yarn v2+

ワークスペースのパッケージ間依存

// packages/app/package.json
{
  "dependencies": {
    "@myorg/shared": "workspace:*"    // yarn v2+ / pnpm
    // npm は "file:../shared" または "*" + workspaces で解決
  }
}

セキュリティ

# 脆弱性の監査
npm audit
yarn audit

# 脆弱性の自動修正（semver互換の範囲で）
npm audit fix

# 破壊的変更を含む修正も実施
npm audit fix --force

コマンド対応表

操作	npm	yarn
全インストール	`npm install`	`yarn`
パッケージ追加	`npm install <pkg>`	`yarn add <pkg>`
dev追加	`npm install -D <pkg>`	`yarn add -D <pkg>`
グローバル追加	`npm install -g <pkg>`	`yarn global add <pkg>`
削除	`npm uninstall <pkg>`	`yarn remove <pkg>`
更新	`npm update`	`yarn upgrade`
scripts実行	`npm run <script>`	`yarn <script>`
一時実行	`npx <pkg>`	`yarn dlx <pkg>`
CI向けインストール	`npm ci`	`yarn --frozen-lockfile`
監査	`npm audit`	`yarn audit`
パッケージ情報	`npm info <pkg>`	`yarn info <pkg>`
一覧表示	`npm list`	`yarn list`
キャッシュクリア	`npm cache clean --force`	`yarn cache clean`
バージョン更新	`npm version <type>`	`yarn version --<type>`
公開	`npm publish`	`yarn publish`

参考リンク

npm Docs - npm公式ドキュメント
npm CLI Commands - npm CLIコマンドリファレンス
Yarn Classic (v1) Docs - Yarn v1公式ドキュメント
Yarn Berry (v2+) Docs - Yarn v2以降の公式ドキュメント
Node.js Corepack - Corepack公式ドキュメント
npm semver calculator - semverバージョン範囲の計算ツール