レジストリヘルス

公開レジストリの監視とスコアリングの仕組みです。

レジストリはディレクトリに追加された後に変更されたり、オフラインになったりします。レジストリヘルスはこれらを継続的にチェックすることで、ユーザーは正常に動作しているかを確認でき、メンテナーは問題を早期に発見できます。

レジストリがオンラインであること、レジストリ形式に従っていること、shadcn CLI で動作することをチェックします。これらのチェックを組み合わせてステータスとスコアを算出します。

レジストリヘルスは実験的機能で、まだ公開されていません。

スコアは収集されていますが、レジストリの表示や順序にはまだ影響しません。スコアリングモデルとしきい値は公開前に変更される可能性があります。

**レジストリヘルスは shadcn/ui レジストリディレクトリに掲載されたレジストリにのみ適用されます。**プライベートレジストリ、プロジェクトに直接設定したレジストリ、owner/repo/item 形式で利用する GitHub レジストリは監視対象外であり、影響も受けません。

監視はレジストリの公開後に開始されます。追加可否の判断には使われず、チェックに失敗しても公開が取り消されることはありません。将来のバージョンでは、利用できないレジストリを API から削除せずに通常の閲覧対象から非表示にする可能性があります。

チェック内容

Cadence	Check	What we look for
Hourly	Registry index	インデックスがオンラインで有効、かつ正しく設定されています。
Daily	Registry items	ローテーションで抽出したアイテムをダウンロード・検証できます。
Weekly	CLI	ローテーション対象のアイテムが `shadcn add --dry-run` で動作します。

アイテムチェックは約30日かけてカタログ全体をローテーションします。定期実行はベストエフォートのため、すべての定期チェックが実行されたと仮定せず、実際に観測された時刻をそれぞれ使用します。

ステータス

ステータスはレジストリの現在の状態を示します:

Status	What it means
Observing	最低24時間かけて最初の24回のインデックスチェックを収集中です。
Healthy	初期観測期間が完了し、最近のチェックが成功しています。
Degraded	レジストリはオンラインですが、1つ以上の最近のチェックが失敗しています。
Unavailable	レジストリインデックスが少なくとも24時間チェックに成功していません。

レジストリは初期観測期間の完了前でも Unavailable になることがあります。以下の場合に Degraded と判定します:

インデックスが3回連続で失敗した場合。
最新のインデックスがレジストリスキーマに一致しない場合。
少なくとも10回のチェック後に、サンプルアイテムの成功率が90%未満の場合。
直近2回の CLI チェックが失敗した場合。

ステータスは全体のスコアが大きく変わる前に直近の問題に反応できます。そのため、スコアが高くても Degraded になることがあります。

各ステータスには短い人間可読の理由が含まれます。API 利用者は安定した statusReason.code を利用するか、statusReason.message を表示できます。モニターからの生エラーは公開されません。

可用性障害の後、レジストリが回復するにはインデックスとスキーマのチェックで2回連続の成功が必要です。その他の劣化は、失敗中のチェックが正常な水準に戻ると解消されます。

スコア

すべてのレジストリは 100点満点で1つのスコアを受け取ります。4つの要素の合計です。各要素の値は100点満点の個別スコアではありません。

Component	Points	What it measures
Reliability	45	過去7日間と30日間のレジストリインデックスの可用性です。
Correctness	25	インデックスとサンプルアイテムがレジストリスキーマに一致しているかです。
Installability	20	サンプルアイテムが `shadcn` CLI で動作するかどうかです。
Registry setup	10	HTTPS・JSON レスポンス・一意なアイテム名・一致するレジストリ名です。

スコアは信頼性と互換性に関するものです。人気・コード品質・デザイン品質・アイテム数を示すものではありません。

点数の計算方法

直近の可用性は古い可用性より重視されます:

Reliability = 45 * (0.65 * availability7d + 0.35 * availability30d)

Correctness はインデックスに最大10点、サンプルアイテムに15点を配点します:

Correctness = 10 * indexSchemaPassRate30d
            + 15 * sampledItemPassRate30d

Installability は CLI チェックに基づきます:

Installability = 20 * dryRunPassRate30d

レジストリ設定には4つのチェックがあり、各2.5点です。設定シグナルがまだ観測されていない場合は、チェック可能になるまで1.25点が付与されます。

各要素は小数点以下3桁に丸められます。公開スコアは丸めた値の合計です。

新規レジストリのスコア

新規レジストリは信頼できるスコアに十分な履歴がありません。初期結果を監視対象レジストリ全体の平均とブレンドします。チェックが蓄積されるにつれて、レジストリ自身の結果の影響が大きくなります。

これにより、1回の成功チェックで満点になったり、1回の失敗チェックで0点になったりするのを防ぎます。また、Observing 状態のレジストリがすでに全体平均に近いスコアを持つ理由も説明できます。

API 利用者向けの平滑化式は次のとおりです:

(successes + globalMean * priorWeight) / (observations + priorWeight)

事前重みは各チェックの頻度に応じます:

Signal	Prior weight
Availability	24
Index schema validity	12
Sampled item validity	10
CLI checks	3

レジストリ全体のデータが不足して平均を計算できない場合、可用性は85%、その他の測定率は90%の事前分布から開始します。式・重み・しきい値の変更には新しい scoreVersion が必要です。

API のヘルスデータ

/r/registries.json は各レジストリに任意の health オブジェクトを追加します。内容は次のとおりです:

現在の status と statusReason。
全体の score と内訳 breakdown。
0〜1の平滑化済み availability7d および availability30d 率。
firstObservedAt、checkedAt、lastSuccessfulCheck のタイムスタンプ。
連携用の schemaVersion と scoreVersion。

このオブジェクトには2つのフラグも含まれます:

monitoringLimited は最新のレジストリインデックス要求が CDN や WAF チャレンジでブロックされたことを意味します。チャレンジレスポンスは可用性やサンプルアイテム検証の失敗として数えません。
hidden は7日連続で利用できない状態が続くと true になります。

レジストリディレクトリは現在 hidden フラグを使用していません。

監視の制限

すべてのチェックは1つのホストランナーから実行されるため、レイテンシには地域による有利不利が生じます。そのため、レイテンシは非公開の診断情報として扱われ、スコアには影響しません。

CDN や WAF チャレンジも別扱いです。チャレンジはランナーがチェックを完了できなかったことを示すもので、すべてのユーザーに対してレジストリが利用できないことを意味しません。

今後の予定

ディレクトリでレジストリヘルスを利用する前に、ベースラインデータを収集・レビューします。監視データが信頼できるようになったら、ランキング・フィルタリング・ヘルス UI を別途公開します。

レジストリディレクトリ例

On This Page

チェック内容ステータススコア点数の計算方法新規レジストリのスコア API のヘルスデータ監視の制限今後の予定

shadcn/uiアプリをVercelにデプロイ

OpenAI、Sonos、Adobeなどに採用されています。

Vercelは、アプリや機能を大規模にデプロイするためのツールとインフラを提供します。