社内npmパッケージの配布に苦労した末、Verdaccioにたどり着いた話

はじめに

社内でしか使わない共通ライブラリやユーティリティ関数、複数リポジトリで使い回したいコンポーネント。こうしたコードをnpm publishしたいけれど、社外に公開するわけにはいかない――そんな悩みを抱えたことはないでしょうか。

Gitのサブモジュールでしのいだり、tarballをSlackで送り合ったりと、涙ぐましい工夫で乗り切っていた時期もありました。しかしバージョン管理は崩れ、依存関係の解決も手作業になり、結局「もうこれ以上パッケージを増やさないでほしい」という空気になっていきます。

そんなときに出会ったのがVerdaccioでした。自前でnpmレジストリを立てられると知り、半信半疑で試したところ、想像以上に手軽に導入できて驚いた記憶があります。この記事では、Verdaccioの特徴から実際の使い方までを紹介します。

Verdaccioとは

Verdaccioは、Node.js製の軽量なプライベートnpmレジストリです。ローカルやオンプレミス、クラウド上に「自分たちだけのnpmレジストリ」を、ほぼ設定なしで構築できます。npm・yarn・pnpmのいずれからも通常のレジストリと同じ感覚で利用できるのが大きな魅力です。

主な特徴

プライベートパッケージの公開 - 社内限定のパッケージをnpm publishできる。外部に一切コードを出さずに配布・バージョン管理が可能
npmjs.orgのプロキシ＆キャッシュ - 公開パッケージへのリクエストをキャッシュしてくれるため、CIのインストール時間短縮やnpmjs.org障害時のフェイルオーバーにも役立つ
複数レジストリの統合 - 社内レジストリと公開レジストリを1つのエンドポイントにまとめて扱える
ゼロコンフィグで起動 - インストール直後にコマンド1つでWeb UI付きのレジストリが立ち上がる

インストール

Verdaccioの動作にはNode.js 18以上が必要です。グローバルインストールが最も手軽な方法です。

# npmの場合
npm install -g verdaccio

# yarnの場合
yarn global add verdaccio

# pnpmの場合
pnpm add -g verdaccio

コンテナ環境で運用したい場合はDockerイメージも公開されています。

docker pull verdaccio/verdaccio
docker run -it --rm --name verdaccio -p 4873:4873 verdaccio/verdaccio

基本的な使い方

インストールが終わったら、コマンド1つで起動できます。

verdaccio

起動すると、以下のようなログが表示され、http://localhost:4873/でWeb UIとレジストリの両方にアクセスできるようになります。

warn --- config file  - ~/.config/verdaccio/config.yaml
warn --- Plugin successfully loaded: verdaccio-htpasswd
warn --- Plugin successfully loaded: verdaccio-audit
warn --- http address - http://localhost:4873/ - verdaccio/6.8.0

npmからこのレジストリを使うには、registryを切り替えます。

npm set registry http://localhost:4873/

初回はユーザー登録が必要です。

npm adduser --registry http://localhost:4873/

あとは通常のパッケージと同じようにインストールできます。未登録のパッケージリクエストは自動的にnpmjs.orgへプロキシされ、レジストリ内にキャッシュされます。

npm install lodash --registry http://localhost:4873/

自作の社内パッケージを公開する場合も、publishコマンドはいつも通りです。

npm publish --registry http://localhost:4873/

デフォルトの設定ファイルは~/.config/verdaccio/config.yamlに生成されます。パッケージごとのアクセス権限は、この設定ファイルのpackagesセクションで細かく制御できます。

packages:
  '@my-company/*':
    access: $authenticated
    publish: $authenticated
    unpublish: $authenticated

  '**':
    access: $all
    publish: $authenticated
    proxy: npmjs

@my-company/スコープ配下は認証済みユーザーのみ公開・取得可能にしつつ、それ以外のパッケージはnpmjs.orgへプロキシする、という設定です。

実践的なユースケース

チーム開発では、社内共通ライブラリの配布だけでなく、次のような使い方も有効です。

CIのインストール高速化 CIランナーの近くにVerdaccioをキャッシュサーバーとして立てておくと、外部レジストリへのアクセス回数が減り、npm ciの実行時間を短縮できます。

依存パッケージの一時的な差し替え サードパーティライブラリに未修正のバグを見つけた際、フォーク版をVerdaccio経由で社内公開し、修正版がリリースされるまでの「つなぎ」として使えます。

docker-composeでの常時起動 開発チーム全体で共有する場合は、docker-composeに組み込んでおくと便利です。

services:
  verdaccio:
    image: verdaccio/verdaccio
    ports:
      - "4873:4873"
    volumes:
      - verdaccio-storage:/verdaccio/storage
      - ./verdaccio-config:/verdaccio/conf

volumes:
  verdaccio-storage: