blog.dopana

戻る

なぜ一部のプロジェクトにはルートディレクトリに.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 npmGlobal/etc/npmrcUser~/.npmrcProject./.npmrcCLI/EnvironmentNPM_CONFIG_REGISTRY

これは以下を意味します:

  • 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の両方を使用する場合、同じことを矛盾する方法で設定しないように注意してください。

実用的な例#

基本的な設定#

.npmrc
# デフォルトレジストリを使用
registry=https://registry.npmjs.org

# 常に正確なバージョン番号を保存(^や~のプレフィックスなし)
save-exact=true
ini

プライベートレジストリの設定#

.npmrc
# 企業スコープのレジストリを設定
@mycompany:registry=https://npm.mycompany.com

# 企業レジストリの認証トークン
//npm.mycompany.com:_authToken=${NPM_TOKEN}

# 他のパッケージのデフォルトレジストリ
registry=https://registry.npmjs.org
ini

GitHub Packagesの設定#

.npmrc
# GitHub Packagesレジストリ
@your-org:registry=https://npm.pkg.github.com

# 認証用のGitHubトークン
//npm.pkg.github.com:_authToken=${GITHUB_TOKEN}
ini

GitLab Package Registryの設定#

.npmrc
# 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}
ini

Bunでの使用#

プロジェクトに.npmrcファイルがある場合、Bunはbun installを実行するときに自動的に読み込みます:

# Bunは.npmrcを読み込み、設定を適用します
bun install

# 現在のBun設定を表示
bun pm config
bash

save-exact=trueを使用する理由#

save-exact=trueが有効になっている場合、パッケージマネージャーは範囲(^1.2.3や~1.2.3など)の代わりに正確なバージョンをpackage.jsonに保存します。

メリット:

  • チーム全員が同じバージョンをインストールできる
  • パッケージが互換性のない更新をリリースしたときの問題を回避できる
  • 本番環境で予測可能な依存関係

デメリット:

  • 依存関係を手動で更新する必要がある
  • パッチ更新を自動的に取得できない

CI/CDでの設定#

CI/CD環境では、通常、ファイルにトークンをコミットする代わりに環境変数を使用します:

.github/workflows/ci.yml
env:
  NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
yaml
.npmrc
# トークンは環境変数から置換されます
//npm.mycompany.com:_authToken=${NPM_TOKEN}
ini

アクティブな設定の表示#

使用されている.npmrcファイルを確認するには:

# npmの場合
npm config list

# Bunの場合
bun pm config
bash

実用的なヒント#

  1. プロジェクト固有の設定には常にプロジェクトレベルの.npmrcを使用
  2. トークンをgitにコミットしない - 代わりに環境変数を使用
  3. 企業のプライベートパッケージにはスコープ付きレジストリを使用
  4. 認証エラーが発生したら設定を確認
  5. プライベートレジストリのドキュメントを読む(GitHub、GitLab、Azure Artifacts)

結論#

.npmrcは、プロジェクトでのパッケージマネージャーの動作を管理するための重要なツールです。Bunのサポートにより、npmからBunに切り替えるときに設定を変更することなく、このファイルを引き続き使用できます。

優先順位と設定方法を理解することで、将来の認証や依存関係管理の問題を回避できます。

References#