npm超入門：外部ライブラリの入れ方と上手な管理

プロジェクトの初期化：package.jsonを作成する

最初に、プロジェクトの基本情報を入れる箱として package.json を用意する。これはプロジェクト名やバージョン、使うスクリプト、依存パッケージの一覧などを記録する設定ファイル。チームで同じ手順を共有するための大事な土台になる。

package.json は手動で書けるが、コマンドで自動作成する方が早くて安全だ。初期化では、後で変えられるので深く悩まずに進めてかまわない。

初期化コマンドと主な項目

• npm init を使う。質問に答えて作る方法と、即座に作る方法がある。
  • 対話式: “`npm init
  • 省略形（既定値で作成）: “`npm init -y
• 主な項目
  • name: プロジェクト名。英小文字とハイフンが無難。
  • version: 初期は 1.0.0 が多い。後で変更できる。
  • scripts: よく使うコマンドのショートカット。後で追加する。
  • dependencies / devDependencies: 入れたパッケージが自動で記録される欄。

実行後にできるファイルとフォルダ

• “`package.json が作成される。
• まだ “`node_modules フォルダはできない。パッケージを入れた時点で作成される。
• リポジトリを使うなら、早い段階で “`.gitignore を用意しておくとよい。

FAQ：package.jsonは手書きでもよい？

手書きでも動くが、書式ミスに気づきにくい。まずは “`npm init で作り、変更は “`npm pkg set key=value のようなコマンドやエディタで行うと安全。

パッケージのインストール（基本操作）

パッケージを「入れる」と、コードで読み込んで使えるようになる。npmでは用途により記録先が分かれる。よく使うのは本番でも必要な依存関係（dependencies）と、開発だけで使う開発依存関係（devDependencies）。

依存関係（Dependencies）：本番でも使うものの入れ方と確認

• 例：Webアプリで本番コードが参照するフレームワークやライブラリ。
• 入れ方
  • “`npm install react のように名前だけで入れられる。
  • バージョン指定：“`npm install react@18.3.1
• 確認方法
  • “`package.json の “`dependencies に名前とバージョン範囲が記録される。
  • “`npm list –depth=0 で上位の入れ物だけ素早く確認できる。

開発依存関係（DevDependencies）：開発だけで使うものの入れ方

• 例：テスト、Linter、フォーマッタ、ビルドツールなど本番コードには含まれない道具。
• 入れ方
  • “`npm install -D eslint のように “`-D（“`–save-dev）を付ける。
• 確認方法
  • “`package.json の “`devDependencies に記録される。

FAQ：peerDependenciesはいつ使うの？

自分のパッケージが「特定のライブラリと一緒に使われる」ことを前提とする時に、要求する側が書く欄。アプリ側では多くの場合、dependencies/devDependencies を使えば足りる。

スクリプトの実行：プロジェクト特有のコマンドを登録する

毎回長いコマンドを打つのは手間がかかる。“`scripts に短い名前で登録すると、誰が実行しても同じ手順になる。タスク名は動詞で始めるとわかりやすい。

package.jsonの編集例

次のような scripts を入れると基本作業が楽になる。

“`

{

“scripts”: {

“start”: “node server.js”,

“dev”: “vite”,

“build”: “tsc -p tsconfig.json && vite build”,

“test”: “vitest”,

“lint”: “eslint .”,

“format”: “prettier –write .”

}

}

“`

• 「実行環境に入っているコマンド」は、“`node_modules/.bin が優先されるため、グローバルインストールは不要なことが多い。

実行方法（npm run と省略形）

• 基本：“`npm run スクリプト名
  • 例：“`npm run build
• 特別な省略：“`start と “`test は “`npm start / “`npm test と短く書ける。
• 引数の渡し方：“`npm run build — –watch のように “`— 以降を渡す。

FAQ：同名のローカルコマンドがある時は？

scripts ではローカルの “`node_modules/.bin が先に解決される。意図しない実行を避けたい場合は、明示的にパスを指定するか、“`npx –no など解決方法を制御する。

バージョンと更新の考え方（SemVer と ^ / ~ / 固定）

パッケージのバージョンは、互換性の考え方（セマンティックバージョニング）で表す。更新範囲を理解すると、思わぬ挙動変化を減らせる。記号の意味を知り、用途に合わせて使い分ける。

セマンティックバージョニングの基本（major/minor/patch）

• 形式は “`MAJOR.MINOR.PATCH（例：1.4.2）。
• 変更の目安
  • MAJOR: 互換性が壊れる変更。
  • MINOR: 機能追加。互換性は保つ想定。
  • PATCH: 不具合修正など小さな変更。

範囲指定の記号（^, ~, なし, 範囲）の意味

• “`^1.4.2: MINOR と PATCH を許す（1.x の間で最新）。
• “`~1.4.2: PATCH だけ許す（1.4.x の間で最新）。
• “`1.4.2: 固定。自動更新しない。
• 範囲指定：“`>=1.4 <2 のように明示する方法もある。

更新範囲のちがいは次の表が目安になる。

FAQ：いつ固定バージョンにすべき？

再現性が特に大切なとき（例：チュートリアル、検証用サンプル、厳密な本番リリース）に固定が役立つ。一方、日常の開発では “`^ や “`~ を使い、“`package-lock.json とテストで安全性を確かめる手が現実的。

package-lock.json と node_modules の役割

同じ依存ツリーを再現するために、npm は lock ファイルと実体フォルダを使う。両者の役割を分けて考えるとトラブルに強くなる。

lockファイルが守ってくれること

• “`package-lock.json は、実際に解決されたバージョンと依存の組み合わせを固定する。
• チーム全員が同じバージョンでインストールできるため、環境差による不具合が減る。
• 依存の取得元や整合性チェック情報（integrity）なども記録される。

クリーンインストール（ci / clean-install）の使いどころ

• “`npm ci は lock ファイルを厳密に守って速く入れるコマンド。
• CI や本番デプロイなど、再現性と速度が大事な場面で有効。
• 依存を変えたくないときは “`npm ci を選ぶ。開発で追加する日は “`npm install を使う、と使い分けると分かりやすい。

FAQ：lockファイルはGitで管理する？

一般的にはバージョン管理に入れる。入れることで、他の人やCIが同じ状態を作れる。ライブラリ開発など特殊な事情がある場合はプロジェクト方針に合わせて判断する。

パッケージの更新・確認・削除

時間がたつと、入れたパッケージの更新や整理が必要になる。状態を確認し、必要に応じて更新や削除を行う。作業前後でテストを実行し、変化を把握すると安全。

状態確認（list, outdated, why）

• 一覧：“`npm list –depth=0
• 古くなったもの：“`npm outdated
• なぜ入っているか：“`npm why パッケージ名

更新（update, install@latest, npx npm-check-updates の紹介）

• ルールに沿って一括更新：“`npm update
• 特定パッケージを最新版へ：“`npm install ライブラリ名@latest
• 設定のバージョン範囲そのものを上げたいときの選択肢
  • 例：“`npx npm-check-updates（外部ツール）。結果を確認してから “`npm install で反映する流れが分かりやすい。
• いずれの場合も変更後にテストを回し、意図しない挙動がないか確かめる。

削除（uninstall）の基本と実行後の変化

• コマンド：“`npm uninstall ライブラリ名
• 変化
  • “`node_modules から該当フォルダが消える。
  • “`package.json の依存欄から記録が消える。
  • “`package-lock.json も更新される。
• 不要になった scripts の見直しもあわせて行うと、次の人が迷わない。

FAQ：globalで入れたものも消せる？

グローバルに入れたものは “`npm uninstall -g パッケージ名 で消す。プロジェクト内の依存とは別管理なので、混同しないよう注意する。

セキュリティとライセンスの基本

ここでは一般的な確認方法だけをまとめる。個別の判断は各プロジェクトの方針や専門家の知見に従う。

npm audit の使いどころと注意

• 既知の脆弱性をチェックする：“`npm audit
• 自動で直せる範囲だけ試す：“`npm audit fix
• 直す前に変更点を読み、テストを回して影響を確認する。自動修正であっても、意図しない変更が入りうる。

ライセンス表示の見方（商用での確認ポイント）

• “`npm view パッケージ名 license や、配布ページの “`LICENSE を確認する。
• 依存先のライセンスも含め、プロジェクトの利用条件に合うか全体で見る。
• 不明点がある場合は、プロジェクトの規定や担当者の判断に従う。

FAQ：auditで自動修正できない時は？

修正候補がない、または互換性の問題で自動適用できないことがある。対策案を読み、アップグレード計画を立てる。状況により代替ライブラリの検討も選択肢になる。

よくあるエラーと対処

つまずきやすい問題は、再現手順→原因→対処の順で整理すると見通しがよい。作業前後にバージョンや設定をメモしておくと、振り返りやすい。

Nodeのバージョンずれ（nvmで合わせる考え方）

• 症状：インストールや実行でエラー。別のPCでは動く。
• 原因：Node のメジャーバージョンが異なる。
• 対処：nvm などのバージョン管理ツールで、プロジェクトが想定するバージョンに切り替える。“`.nvmrc を置いておくと、チーム全体で合わせやすい。

キャッシュやネットワーク（npm cache, プロキシ設定）

• 症状：インストールが途中で止まる、整合性エラーが出る。
• 対処
  • キャッシュを確認：“`npm cache verify
  • 必要ならクリア：“`npm cache clean –force
  • 企業ネットワークではプロキシ設定の確認も有効。

FAQ：npxで動くのにnpm scriptで失敗するのはなぜ？

解決するコマンドの優先順位や実行ディレクトリが異なるため。“`scripts ではローカルのバイナリが優先される。絶対パス指定やカレントディレクトリの見直しで改善することが多い。

付録：依存の種類の早見表（参考）