リリースガイド

このドキュメントでは、@lh-ui/vue3 を npm パブリックリポジトリへリリースする方法と、プライベートサーバーへホスティングする方法（tarball 直リンクと registry メタデータの 2 つの方式）を説明します。

リリースは手動と CI 自動のデュアルチャネルをサポートしています：ローカルで changeset コマンドを実行し、人がバージョン番号と変更説明を確認した上で发包します（下記「リリースフロー」）。main へのプッシュ時に .changeset/** に変更があれば、GitHub Actions が自動的に version + publish を実行します（「GitHub Actions による自動リリース」を参照）。

前提準備

1. npm アカウントと scope の所有権

npm にアカウントを登録し、二要素認証（2FA）を有効にします。
あなたのアカウントが @lh-ui という scope のリリース権限を持っていることを確認してください：scope は早い者勝ちで、初めて @lh-ui/* パッケージをリリースしたアカウントがその scope の owner になります。

ローカルでログインします：

bash

npm whoami          # 現在ログインしているアカウントを確認
npm login           # 未ログイン時にプロンプトに従ってログイン + 2FA を完了

2. registry がパブリックリポジトリを指していることを確認

リポジトリルートの .npmrc には shamefully-hoist = true しか設定されておらず、registry は固定されておらず、デフォルトで https://registry.npmjs.org/ に向かいます。package.json の publishConfig もパブリックリポジトリに固定されています：

json

"publishConfig": {
  "access": "public",
  "registry": "https://registry.npmjs.org/"
}

リポジトリルートの .npmrc にプライベート registry アドレスを書かないでください —— 发包までプライベートソースに導かれてしまいます。registry を一時的に切り替える場合は、プロジェクト外のユーザーレベル ~/.npmrc またはコマンドラインパラメータを使ってください。

3. 一回のリリースに何が含まれるか

files のホワイトリストにはビルド産物しか公開しません：es/（ESM + 型 + コンポーネントスタイル）、lib/（CJS）、dist/（UMD + 完全なスタイル）。ソース、ドキュメント、テスト、スクリプトはすべて .npmignore で除外されます。リリースコマンドの実行時に prepublishOnly が自動的に pnpm build を先に実行するため、手動で事前にビルドする必要はありません。

リリースフロー

ステップ 1：changeset を書く

ユーザーに見えるすべての変更には changeset を一つ付けるべきです。この変更で既に書いている場合は、ステップ 2 に進んでください。

bash

pnpm changeset

インタラクティブなプロンプトに従って @lh-ui/vue3、bump タイプ（major / minor / patch）、変更説明を選択します。

注意：本リポジトリの changeset は累積的です。 現在 .changeset/ には数十条の未消費 changeset が蓄積されており、ステップ 2 の changeset version を実行すると一度にすべて消費され、同じバージョンにマージされます。段階的にリリースしたい場合は、先に git ブランチまたは手動で一部の changeset ファイルを移動させてペースを制御する必要があります。

ステップ 2：バージョン番号の引き上げ、CHANGELOG の生成

bash

pnpm changeset:version

このコマンドは以下を行います：

changeset の最高 bump レベルに基づいて新バージョン番号を計算し、package.json に書き込む
すべての changeset を集約して CHANGELOG.md を生成する
消費された .changeset/*.md を削除する（config.json で commit: false なので自動コミットされない）

実行後に必ず人工確認を行ってください：

bash

git status              # changeset が消費され、CHANGELOG が生成されたことを確認
git diff package.json   # バージョン番号が想定通りかを確認

ステップ 3：リリース

bash

pnpm changeset:publish

内部では pnpm publish を実行します。フローは以下の通りです：

prepublishOnly をトリガー → pnpm build（ESM / CJS / UMD / 型 / スタイルの完全ビルド）
publishConfig に従ってパッケージ化し npm パブリックリポジトリへプッシュする
git tag を生成してプッシュする（フォーマット @lh-ui/vue3@<version>）

publishConfig.access は public なので、scoped パッケージも公開され、追加で --access public を付ける必要はありません。

ステップ 4：プッシュ（あなたが実行）

bash

git push --follow-tags

リリース前の自己チェック

正式な发包の前に、dry-run で実際のパッケージ内容を確認します：

bash

npm pack --dry-run

出力に以下が含まれることを確認します：

es/、lib/、dist/ の 3 つのディレクトリのみ
src/、packages/、docs/、tests/、scripts/、ai/ は含まれない
サイズが妥当（UMD 完全パッケージは約 600KB、完全なスタイルは約 700KB で、想定範囲内）

リリース後の検証

bash

# 1. npm で新バージョンが確認できる
npm view @lh-ui/vue3
npm view @lh-ui/vue3 versions

# 2. 新しくサンドボックスプロジェクトを作って 3 つのモジュール形式を実測する
pnpm create vite verify-pkg --template vue-ts
cd verify-pkg && pnpm add @lh-ui/vue3

サンドボックスプロジェクトで一つずつ検証します：

検証項目	書き方
完全なインポート（ESM）	`import LhUiPlus from '@lh-ui/vue3'` + `import '@lh-ui/vue3/dist/index.css'`
コンポーネントのオンデマンドインポート	`import { LhButton } from '@lh-ui/vue3'`
スタイルのオンデマンドインポート（sass 必要）	`import '@lh-ui/vue3/style/button'`
スタイルのオンデマンドインポート（sass 不要）	`import '@lh-ui/vue3/style-css/button'`
テーマユーティリティ	`import { getThemeVars } from '@lh-ui/vue3/theme'`
CDN（数分後にリフレッシュ）	`https://unpkg.com/@lh-ui/vue3`

プライベートサーバーホスティング（静的 tarball）

npm パブリックリポジトリがメインのリリースチャネルです。自己ホストのミラーが必要な場合（イントラネットでの使用、npm が遮断されている、特定バージョンに固定したい）、tarball を自分のサーバーに置くのが最も軽量なソリューションで、プライベート npm registry を構築する必要はありません。

1. tarball のパッケージング

bash

pnpm build
npm pack

生成されるファイル名は lh-ui-vue3-<version>.tgz です —— npm は scope の @lh-ui/ を lh-ui-vue3- に変換します（スラッシュがハイフンになる）。npm pack --dry-run で事前確認もできます。

2. サーバーへのアップロード

既存の nginx サイトのディレクトリ约定に従います（ドキュメントサイトは /home/webuser/nginx/lh-ui/vue3/ にデプロイ）。その下に packages/ ディレクトリを新しく作り、バージョンごとにディレクトリを分けて配置します：

/home/webuser/nginx/lh-ui/vue3/
├── index.html              # ドキュメントサイト
└── packages/
    ├── 1.0.0/
    │   └── lh-ui-vue3-1.0.0.tgz
    ├── 1.1.0/
    │   └── lh-ui-vue3-1.1.0.tgz
    └── latest              # ソフトリンク、現在の推奨バージョンを指す
        └── lh-ui-vue3-1.1.0.tgz

対応する URL：

https://www.lhgb.top/lhui/vue3/packages/1.0.0/lh-ui-vue3-1.0.0.tgz

packages/ は静的ファイルディレクトリで、既存サイトの nginx 設定をそのまま使えます。新しい location は不要です：

nginx

# 既存のドキュメントサイト location は /lhui/vue3/ プレフィックスをカバーしており、
# packages/ はそのサブディレクトリとして自動的にアクセス可能。
# .tgz の Content-Type がダウンロード可能であることだけ確認すればよい
# （nginx のデフォルト octet-stream で問題ない）
location /lhui/vue3/ {
    alias /home/webuser/nginx/lh-ui/vue3/;
    autoindex off;
}

3. プライベートサーバーからのインストール

3 つの等価な書き方のうち、どれか一つを選びます：

bash

# pnpm
pnpm add https://www.lhgb.top/lhui/vue3/packages/1.0.0/lh-ui-vue3-1.0.0.tgz

# npm
npm install https://www.lhgb.top/lhui/vue3/packages/1.0.0/lh-ui-vue3-1.0.0.tgz

# yarn
yarn add https://www.lhgb.top/lhui/vue3/packages/1.0.0/lh-ui-vue3-1.0.0.tgz

または package.json に直接書き込みます：

json

{
  "dependencies": {
    "@lh-ui/vue3": "https://www.lhgb.top/lhui/vue3/packages/1.0.0/lh-ui-vue3-1.0.0.tgz"
  }
}

4. 注意事項

registry の依存解決を bypass する：tarball インストールは registry を参照せず、依存は tarball 内の宣言から直接取得します。本パッケージはランタイム dependencies がゼロで peerDependencies.vue しかないため、消費側のプロジェクトに Vue 3 があればインストールでき、実行できます。
バージョンメタデータがない：npm update は tarball 依存には効きません。アップグレードは必ず手動で URL を置き換える必要があります（または latest のソフトリンクを変更してから再インストール）。バージョンロックミラーには適していますが、頻繁な更新には不向きです。
https が必須：pnpm / npm / yarn はデフォルトで http の tarball アドレスを拒否します。
pnpm-lock.yaml には完全な URL + integrity hash が書かれる：チームでのコラボレーション時にロックファイルで npm にアクセスすることなくインストールを正しく再現できます。

プライベートサーバーホスティング（registry メタデータ）

上記の tarball 直リンクも使えますが、pnpm update が効かず lockfile には URL の羅列になります。消費側が通常のパッケージと同じように pnpm add @lhgb/vue3 でバージョン解決と dist-tags を利用したい場合は、Nginx の静的ディレクトリに npm registry メタデータを一つ偽装させ、読み取り専用 registry として運用できます。両方式は共存できます。

1. パッケージング

bash

pnpm build
node scripts/pack-private.mjs

スクリプトが行うこと：同一のビルド産物を @lhgb/vue3 にリネームし（name / publishConfig のみ異なる）、npm pack で tarball を産出し、integrity（sha512）と shasum（sha1）を計算し、registry メタデータ JSON を組み立てて private-registry/ に出力します：

private-registry/
├── @lhgb/vue3              # メタデータ JSON（拡張子なし）
└── tarballs/@lhgb/vue3/
    └── lhgb-vue3-1.0.0.tgz

よく使うパラメータ：

--dry-run：生成されるファイル一覧とメタデータを表示するだけでディスクに書き込まない。リリース前の確認に使用
--incremental：既存のメタデータを読み込んで新バージョンをマージし、過去のバージョンを上書きしない

2. サーバーへのデプロイ

private-registry/ の内容をサーバーのディレクトリにアップロードし、scripts/nginx-private-registry.conf.example の location を適用します（ドキュメントサイト /lhui/vue3/ と同じ Nginx で、location は独立）：

/home/webuser/nginx/registry/
├── @lhgb/vue3
└── tarballs/@lhgb/vue3/
    └── lhgb-vue3-1.0.0.tgz

Nginx 設定のポイントは default_type application/json です —— メタデータファイルには拡張子がなく、型を強制宣言しないとクライアントがプレーンテキストとして解析して失敗します。完全な設定は scripts/nginx-private-registry.conf.example を参照してください（.tgz はトップレベルの正規 location に単独で置く必要があり、^~ /lhgb/ に入れ子にしてはいけません。そうしないとプレフィックスマッチが正規マッチをスキップしてしまいます）：

nginx

location ^~ /lhgb/ {
  alias /home/webuser/nginx/registry/;
  default_type application/json;
  autoindex off;
  expires 5m;
}

location ~ ^/lhgb/(.+\.tgz)$ {
  alias /home/webuser/nginx/registry/$1;
  default_type application/octet-stream;
  expires 1y;
  add_header Cache-Control "public, immutable" always;
}

3. プライベート registry からのインストール

プロジェクトレベルまたはユーザーレベルの .npmrc に一行を追加します：

ini

@lhgb:registry=https://www.lhgb.top/lhgb

3 つのパッケージマネージャで統一されています：

bash

pnpm add @lhgb/vue3
# または
npm install @lhgb/vue3
# または
yarn add @lhgb/vue3

4. パブリックパッケージとの関係

@lhgb/vue3 と @lh-ui/vue3 は同源・同バージョンで、ビルド産物は完全に同一です。name と registry が異なるだけで、両者は互換性があります：

イントラネット / npm 遮断 / リリースソースを固定したい場合は @lhgb/vue3
外部に公開し、unpkg / jsdelivr の CDN でヒットさせたい場合は @lh-ui/vue3

5. 注意事項

メタデータはインクリメンタルに更新する：毎回の发包後に --incremental で新バージョンをマージしてください。直接上書きすると過去のバージョンのメタデータが失われ、旧バージョンがインストールできなくなります。
tarball は移動できない：メタデータ内の tarball URL は絶対パスで、ファイルの場所と URL が一対一で対応している必要があります。
同様に https が必須：pnpm / npm / yarn はデフォルトで http アドレスを拒否します。
@lhgb registry をリポジトリルートの .npmrc に書かない：ルートの .npmrc には shamefully-hoist = true だけを残し、プライベートサーバーのアドレスはユーザーレベルの ~/.npmrc に書いて、发包パイプラインの汚染を避けてください。

GitHub Actions による自動リリース

手動フローに加え、.github/workflows/release.yml が自動リリースチャネルを提供します：

トリガー条件：main へのプッシュで .changeset/** または package.json に変更がある場合。またはリポジトリの Actions ページからの手動トリガー（workflow_dispatch）。
挙動：pnpm build + pnpm verify:dts を実行した後に changesets/action の version + publish を実行します。リリース対象の changeset がない場合は何もしません。そのため push にフックしていても安全です。
必要な secret：リポジトリの Settings → Secrets and variables → Actions で NPM_TOKEN を設定します —— npm で Granular Access Token を生成し、@lh-ui 組織の publish 権限を付与してください。

手動と自動のチャネルは共存できます：ローカルの pnpm changeset:publish は一回ごとの发包を人工確認したい場合に適し、CI は changeset を蓄積した後に自動で雪だるま式にリリースする場合に適しています。

ロールバック

bash

# あるバージョンを非推奨としてマークする（推奨。既にインストール済みのユーザーには影響しない）
npm deprecate @lh-ui/vue3@1.0.0 "このバージョンには xx の問題があります。1.0.1 にアップグレードしてください"

# 完全に取り下げる：リリースから 72 時間以内かつ、他のパッケージが依存していない場合のみ可能
npm unpublish @lh-ui/vue3@1.0.0

CDN（unpkg / jsdelivr）のキャッシュは数時間から一日のうちに失効します。ロールバック後、サンドボックスプロジェクトでバージョン番号付きの URL を使い、旧バージョンがまだインストール可能かを検証できます。

リリースガイド ​

前提準備 ​

1. npm アカウントと scope の所有権 ​

2. registry がパブリックリポジトリを指していることを確認 ​

3. 一回のリリースに何が含まれるか ​

リリースフロー ​

ステップ 1：changeset を書く ​

ステップ 2：バージョン番号の引き上げ、CHANGELOG の生成 ​

ステップ 3：リリース ​

ステップ 4：プッシュ（あなたが実行） ​

リリース前の自己チェック ​

リリース後の検証 ​

プライベートサーバーホスティング（静的 tarball） ​

1. tarball のパッケージング ​

2. サーバーへのアップロード ​

3. プライベートサーバーからのインストール ​

4. 注意事項 ​

プライベートサーバーホスティング（registry メタデータ） ​

1. パッケージング ​

2. サーバーへのデプロイ ​

3. プライベート registry からのインストール ​

4. パブリックパッケージとの関係 ​

5. 注意事項 ​

GitHub Actions による自動リリース ​

ロールバック ​

リリースガイド

前提準備

1. npm アカウントと scope の所有権

2. registry がパブリックリポジトリを指していることを確認

3. 一回のリリースに何が含まれるか

リリースフロー

ステップ 1：changeset を書く

ステップ 2：バージョン番号の引き上げ、CHANGELOG の生成

ステップ 3：リリース

ステップ 4：プッシュ（あなたが実行）

リリース前の自己チェック

リリース後の検証

プライベートサーバーホスティング（静的 tarball）

1. tarball のパッケージング

2. サーバーへのアップロード

3. プライベートサーバーからのインストール

4. 注意事項

プライベートサーバーホスティング（registry メタデータ）

1. パッケージング

2. サーバーへのデプロイ

3. プライベート registry からのインストール

4. パブリックパッケージとの関係

5. 注意事項

GitHub Actions による自動リリース

ロールバック