sumisonic notes

GitLab Package Registry と npm

3 min read

概要

GitLab Package Registry を使って社内 npm パッケージを管理する仕組み。 npm の公開レジストリ (npmjs.org) の代わりに、自前 GitLab をレジストリとして使う。

レジストリの3つのレベル

レベルURL パターン用途
インスタンス/api/v4/packages/npm/install（全プロジェクト横断）
グループ/api/v4/groups/<GROUP_ID>/-/packages/npm/install（グループ内限定）
プロジェクト/api/v4/projects/<PROJECT_ID>/packages/npm/publish + install

重要な制約

  • publish はプロジェクトレベルのみ （インスタンス/グループレベルでは 404）
  • install はどのレベルでも可能
  • tarball のダウンロード URL はプロジェクトレベルになるため、認証行もプロジェクトレベルのパスが必要

スコープ付きパッケージの命名規約

インスタンスレベルのレジストリを使う場合:

  • スコープ名 = GitLab のトップレベルグループ名（slug） と一致する必要がある
  • 例: グループ slug が sumito → スコープは @sumito
  • パッケージ名例: @sumito/create-fpx-app

グループ/プロジェクトレベルなら命名規約の制約はない。

.npmrc の認証設定

パスマッチングの仕様

  • .npmrc の認証行はパスの 前方一致 でマッチする
  • ワイルドカードは使えない
  • ドメインレベル（ //git.rzm.io/:_authToken…= ）も効かない場合がある

実用的な設定パターン（~/.npmrc）

@sumito:registry=https://git.rzm.io/api/v4/packages/npm/
//git.rzm.io/api/v4/packages/npm/:_authToken=glpat-xxx
//git.rzm.io/api/v4/projects/:_authToken=glpat-xxx
  • 1行目: @sumito スコープをインスタンスレベルに紐付け
  • 2行目: メタデータ取得用の認証
  • 3行目: tarball ダウンロード + publish 用の認証（プロジェクト ID 不問で全プロジェクトに対応）

publish 用のプロジェクト .npmrc

プロジェクトルートの .npmrc で @sumito:registry をプロジェクトレベルに上書き:

@sumito:registry=https://git.rzm.io/api/v4/projects/1406/packages/npm/
//git.rzm.io/api/v4/projects/1406/packages/npm/:_authToken=${GITLAB_NPM_PUBLISH_TOKEN}

~/.npmrc よりプロジェクトの .npmrc が優先される。

package.json の注意点

files フィールドと .npmignore の関係

  • files で指定したものは .npmignore による除外が 効かない
  • files 内で ! パターンで除外する必要がある
"files": [
  "dist",
  "templates",
  "!templates/**/node_modules",
  "!templates/**/.next",
  "!templates/**/out"
]

publishConfig

package.json に publish 先レジストリを指定:

"publishConfig": {
  "registry": "https://git.rzm.io/api/v4/projects/1406/packages/npm/"
}

pnpm create の仕組み

pnpm create @scope/xxx は自動的に @scope/create-xxx パッケージを探して実行する。

コマンド探すパッケージ
pnpm create @sumito/fpx-app@sumito/create-fpx-app
pnpm create next-appcreate-next-app

npx の場合はパッケージ名をそのまま指定: npx @sumito/create-fpx-app

publish コマンド

pnpm publish --no-git-checks

--no-git-checks: feature ブランチや未コミット変更があっても publish 可能にするフラグ。 prepublishOnly スクリプトがあれば自動でビルドも走る。

GitLab での管理

  • パッケージ削除: Deploy → Package Registry → Delete
  • リリース削除: Deploy → Releases → Delete
  • Git 履歴を削除しても Package Registry / Releases には影響なし

グラフビュー