会社のプロジェクトでプライベートパッケージ（Private Package）を使用する必要があるのに、.npmrcの設定で行き詰まっていませんか？

なぜTokenを設定したのに、まだ404 Not Foundが表示されるのでしょうか？

会社に複数のチーム、複数のパッケージ（例：@frontend、@backend）がある場合、.npmrcをどのように優雅に管理すればよいでしょうか？

.npmrcの2つの迷信を解き明かす

.npmrcを理解するには、まずそれがどのように機能するかを理解する必要があります。

簡単に言えば、その核心的なロジックは2つのことだけです：スコープマッピング（Scope Mapping）と認証（Authentication）。

1. スコープマッピング（Scope Mapping）

これはnpmに伝えています：@companyで始まるパッケージを見つけた場合、公式のnpmjs.orgを探さず、指定されたGitLab Registryを探しに行きます。

@company:registry=https://gitlab.com/api/v4/groups/100/-/packages/npm/

2. 認証（Authentication）

アドレスがあっても、鍵が必要です。鍵はあなたのAuthTokenです。

ここに非常に重要なルールがあります：Registry URLとAuthTokenのパスは「完全に一致」しなければなりません。

# ✅ 正しい：パスは上で定義されたregistryと完全に同じです
//gitlab.com/api/v4/groups/100/-/packages/npm/:_authToken=${GITLAB_TOKEN}

# ❌ 間違い：パスが一致しないため、権限エラーが発生します
//gitlab.com/api/v4/:_authToken=${GITLAB_TOKEN}

多くの人が設定に失敗するのは、パスにスラッシュが多かったり、階層が少なかったりするためです。

依存関係地獄と404エラー

最も頭の痛い状況はこれです：パッケージAをインストールした結果、それがパッケージB（これもプライベート）に依存しており、npmが404 Not Foundを吐き出す場合です。

なぜこうなるのでしょうか？それは、正しい対応関係がない場合、npmは依存関係を解決する際に迷子になるからです。

特に、異なるGitLab Groupに2つの異なるスコープ（例：@team-aと@team-b）がある場合、.npmrcは非常に複雑で保守が難しくなります。さらに、異なるRegistryには異なるTokenが必要な場合があり、これらの環境変数を管理するだけで手一杯になります。

もっと賢い方法はあるのでしょうか？

推奨ソリューション：統一ダウンロードGroup Registry & 独立公開Project Registry

なぜそうするのか？

設定の実践

このテンプレートを直接コピーできます：

Tokenを保護する作業は環境変数に任せ、絶対にコードに直接Tokenを書かないように覚えておいてください！

# .npmrc
# 汎用ドメインレベルのauth token（すべてのgroupおよびprojectレベルのインストールリクエストをカバー）
//gitlab.com/:_authToken=${GITLAB_NPM_TOKEN}

# 公開用：project-level auth token（npm publishは正確なパス一致が必要）
//gitlab.com/api/v4/projects/YOUR_PROJECT_ID/packages/npm/:_authToken=${GITLAB_NPM_TOKEN}

# @company scopeはgroupレベルのregistryを使用
# すべての @company/* パッケージはこのregistryからインストールされます
@company:registry=https://gitlab.com/api/v4/groups/YOUR_GROUP_ID/-/packages/npm/

# その他の公開パッケージは公式ライブラリに行きます
registry=https://registry.npmjs.org/

package.jsonでpublishConfigを設定し、パッケージを対応するGitLab Project Registryに公開します。

{
  "name": "@company/my-package",
  "publishConfig": {
    "@company:registry": "https://gitlab.com/api/v4/projects/YOUR_PROJECT_ID/packages/npm/"
  }
}

結論

**「統一ダウンロードGroup Registry」と「独立公開Project Registry」**の戦略を通じて、保守コストを大幅に削減し、開発プロセスをスムーズにすることができます。

これらのロジックを習得すれば、GitLab NPM Registryは会社の開発プロセスにおける強力な助っ人になります！