npm エコシステム

npm は Node.js とともに配布されるパッケージマネージャーです。パッケージのインストール、プロジェクトスクリプトの実行、レジストリへのパッケージ公開、依存関係の解決結果の記録を行い、チームがアプリケーションのビルドを再現できるようにします。

パッケージメタデータ #

すべての npm プロジェクトは package.json で記述します。最も重要なフィールドは、パッケージを識別し、スクリプトを定義し、依存関係を宣言します。

json

{
  "name": "example-service",
  "private": true,
  "type": "module",
  "scripts": {
    "test": "node --test",
    "start": "node src/server.js"
  },
  "dependencies": {
    "fastify": "^5.0.0"
  },
  "devDependencies": {
    "typescript": "^5.0.0"
  },
  "engines": {
    "node": ">=20"
  }
}

dependencies は本番環境で必要です。devDependencies は開発、テスト、ビルドを支援します。private: true とマークされたパッケージは誤って公開できません。

type フィールドは .js ファイルの解釈方法を制御します。"module" は ECMAScript モジュールを選択し、省略時はデフォルトの CommonJS 動作が適用されます。両方のモジュールシステムをサポートするパッケージでは、exports フィールドを使用して意図した公開エントリポイントを公開できます。

バージョン範囲とロックファイル #

npm のバージョンはセマンティックバージョニング、つまり major.minor.patch に従います。 ^5.2.1 のようなキャレット範囲は、次のメジャーリリース前の互換性のあるマイナーおよびパッチ更新を許可し、~5.2.1 のようなチルダ範囲はパッチ更新だけを許可します。厳密なバージョンは最も強い制約になります。

package.json は許可される範囲を表し、package-lock.json は npm が解決した正確な依存関係ツリーを記録します。アプリケーションでは両方をコミットし、継続的インテグレーションでは npm ci を使用してください。npm install と異なり、npm ci はロックファイルがマニフェストと一致することを要求し、クリーンで固定されたツリーをインストールします。

npm install
npm run test
npm ci
npm outdated
npm update

スクリプトと実行可能ファイル #

npm run <script> は scripts フィールドのコマンドを実行し、node_modules/.bin のローカル実行可能ファイルを PATH に追加します。これにより、グローバルインストールを要求せずに npm run lint を移植可能な形で実行できます。-- の後に引数を渡します。

npm run test -- --watch

一時的なコマンド実行には npx <package> または npm exec <package> を使用します。コントリビューターや CI が繰り返し実行するコマンドには、プロジェクトの依存関係とスクリプトを優先してください。

レジストリと公開 #

デフォルトは公開 npm レジストリですが、.npmrc でスコープ用のレジストリを選択できます。

ini

@acme:registry=https://registry.example.com/

特に CI では、リポジトリ外で管理するトークンで認証します。ライブラリを公開する前に、 files、.npmignore、exports、ライセンス、生成された tarball を確認してください。

npm pack --dry-run
npm publish

ライブラリは意図したランタイムファイルだけを公開し、サポートする Node.js バージョンを文書化してください。アプリケーションは通常、非公開のまま公開せずにデプロイします。