Node.jsとBunの.npmrcファイル
.npmrcの包括的ガイド - Node.jsとBunのレジストリ、認証、インストール設定
なぜ一部のプロジェクトにはルートディレクトリに.npmrcファイルがあるのか、疑問に思ったことはありませんか?あるいは、企業のプライベートレジストリを設定する方法を知りたいですか?.npmrcファイルは、npm、pnpm、yarn、Bunなどのパッケージマネージャーの動作を制御するための鍵です。
この記事では、.npmrcがどのように機能するか、特に超高速な新しいパッケージマネージャーであるBunを使用する場合について説明します。
.npmrcが重要な理由#
企業のプライベートパッケージを使用するプロジェクトで作業していると想像してください。npm installやbun installを実行するたびにユーザー名とパスワードを入力しなければならないとしたら、非常に frustrating でしょう。.npmrcは設定を一元管理することでこの問題を解決します。
[!NOTE]
.npmrcはパッケージマネージャーの設定ファイルとして機能します。これは、環境変数用の.envに似ていますが、npm/Bun専用です。
.npmrcとは何ですか?#
.npmrcは、パッケージマネージャー(npm、pnpm、yarn、Bun)のオプションを設定するためのキーと値のペアの設定ファイルです。以下を含めることができます:
- レジストリURL(パッケージのダウンロード元)
- 認証トークン(プライベートレジストリへのアクセス用)
save-exact、engine-strictなどのインストール設定
.npmrcの優先順位#
パッケージマネージャーは、複数の場所で.npmrcファイルを探します。優先順位は低いから高い順です:
これは以下を意味します:
- Default: npmのデフォルト設定
- Global: システム全体のファイル(通常
/etc/npmrc) - User: ホームディレクトリのユーザーごとのファイル(
~/.npmrc) - Project: プロジェクトルートのローカルファイル(
./.npmrc)- プロジェクト固有の設定を構成する場所 - CLI/Environment: コマンドラインフラグまたは環境変数(最高優先順位)
[!TIP] 同じ設定が複数の場所にある場合、優先順位が高いものが低いものを上書きします。
Bunが.npmrcを処理する方法#
Bunの強みの一つは、標準的な.npmrcファイルとの完全な互換性です。レジストリや認証設定を変更することなく、既存のNode.jsプロジェクトにBunを導入できます。
Bunがサポートする設定#
Bunは以下の一般的な.npmrcディレクティブをサポートしています:
- レジストリURL: デフォルトレジストリとスコープ付きレジストリの設定
- スコープ付きレジストリ: 特定のスコープ(例:
@mycompany)に特定のレジストリを割り当て - 認証トークン:
_authToken、_auth、username、_password、email - プロジェクトオプション:
save-exact=true、link-workspace-packages
Bunfig.toml - Bunのネイティブな代替案#
Bunにはbunfig.tomlという独自のネイティブ設定ファイルもありますが、ツール間の互換性のために.npmrcを引き続き尊重します。
[!WARNING]
.npmrcとbunfig.tomlの両方を使用する場合、同じことを矛盾する方法で設定しないように注意してください。
実用的な例#
基本的な設定#
# デフォルトレジストリを使用
registry=https://registry.npmjs.org
# 常に正確なバージョン番号を保存(^や~のプレフィックスなし)
save-exact=trueiniプライベートレジストリの設定#
# 企業スコープのレジストリを設定
@mycompany:registry=https://npm.mycompany.com
# 企業レジストリの認証トークン
//npm.mycompany.com:_authToken=${NPM_TOKEN}
# 他のパッケージのデフォルトレジストリ
registry=https://registry.npmjs.orginiGitHub Packagesの設定#
# GitHub Packagesレジストリ
@your-org:registry=https://npm.pkg.github.com
# 認証用のGitHubトークン
//npm.pkg.github.com:_authToken=${GITHUB_TOKEN}iniGitLab Package Registryの設定#
# GitLab Package Registry
@your-group:registry=https://gitlab.com/api/v4/projects/PROJECT_ID/packages/npm/
# GitLabトークン
//gitlab.com/api/v4/projects/PROJECT_ID/packages/npm/:_authToken=${GITLAB_TOKEN}iniBunでの使用#
プロジェクトに.npmrcファイルがある場合、Bunはbun installを実行するときに自動的に読み込みます:
# Bunは.npmrcを読み込み、設定を適用します
bun install
# 現在のBun設定を表示
bun pm configbashsave-exact=trueを使用する理由#
save-exact=trueが有効になっている場合、パッケージマネージャーは範囲(^1.2.3や~1.2.3など)の代わりに正確なバージョンをpackage.jsonに保存します。
メリット:
- チーム全員が同じバージョンをインストールできる
- パッケージが互換性のない更新をリリースしたときの問題を回避できる
- 本番環境で予測可能な依存関係
デメリット:
- 依存関係を手動で更新する必要がある
- パッチ更新を自動的に取得できない
CI/CDでの設定#
CI/CD環境では、通常、ファイルにトークンをコミットする代わりに環境変数を使用します:
env:
NPM_TOKEN: ${{ secrets.NPM_TOKEN }}yaml# トークンは環境変数から置換されます
//npm.mycompany.com:_authToken=${NPM_TOKEN}iniアクティブな設定の表示#
使用されている.npmrcファイルを確認するには:
# npmの場合
npm config list
# Bunの場合
bun pm configbash実用的なヒント#
- プロジェクト固有の設定には常にプロジェクトレベルの
.npmrcを使用 - トークンをgitにコミットしない - 代わりに環境変数を使用
- 企業のプライベートパッケージにはスコープ付きレジストリを使用
- 認証エラーが発生したら設定を確認
- プライベートレジストリのドキュメントを読む(GitHub、GitLab、Azure Artifacts)
結論#
.npmrcは、プロジェクトでのパッケージマネージャーの動作を管理するための重要なツールです。Bunのサポートにより、npmからBunに切り替えるときに設定を変更することなく、このファイルを引き続き使用できます。
優先順位と設定方法を理解することで、将来の認証や依存関係管理の問題を回避できます。