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

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

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

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

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

簡単に言えば、そのコアロジックはたった2つのことです：Scope マッピングと認証。

1. Scope マッピング（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}

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

依存関係地獄と 404 エラー

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

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

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

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

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

なぜそうするのか？

設定の実践

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

Token を保護する作業は環境変数に任せ、コードに Token を直接書き込まないようにしてください！

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

# GitLab npm registry 認証設定
# 共通の gitlab.com auth token を使用（すべての group および project レベルのリクエストをカバー）
//gitlab.com/api/v4/groups/YOUR_GROUP_ID/-/packages/npm/:_authToken=${GITLAB_NPM_TOKEN}
# プロジェクトの registry を使用してパッケージを公開
//gitlab.com/api/v4/projects/YOUR_PROJECT_ID/packages/npm/:_authToken=${GITLAB_NPM_TOKEN}


# 他の公開パッケージは公式レジストリへ
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 は会社の開発プロセスにおいて強力な助っ人となるでしょう！