プラグインの安定性ティア

AppKit の plugin には、API の成熟度と破壊的変更の可能性を示す 2 段階の安定性ティアがあります。

ティア

インポートパスは安定性を示す最も重要なシグナルです。/beta からインポートすることは、破壊的変更が発生し得ることに明示的に同意したものとみなされます。

昇格パス

昇格は一方向です。plugin はどのティアからでも開始できます。

使い方

ティア別の plugin のインポート

// GA plugin
import { server, analytics } from "@databricks/appkit";

// Beta plugin
import { someBetaPlugin } from "@databricks/appkit/beta";

UI コンポーネント

@databricks/appkit-ui も同じパターンに従います。

import { SomeComponent } from "@databricks/appkit-ui/react/beta";
import { someUtil } from "@databricks/appkit-ui/js/beta";

CLI コマンド

安定性付きで plugin を一覧表示する

npx appkit plugin list

出力には、各pluginのティアを示すSTABILITY列が含まれます。

安定性を指定した plugin の作成

npx appkit plugin create

対話型フローでは、安定性レベルの入力を求められます (デフォルトは GA) 。

plugin の昇格

# beta から GA へ昇格
npx appkit plugin promote my-plugin --to ga

# ファイルを変更せずに変更内容をプレビュー
npx appkit plugin promote my-plugin --to ga --dry-run

promote コマンドの動作は次のとおりです。

• plugin の manifest.json の stability フィールドを更新します
• project 内の .ts/.tsx ファイルのインポートパスを一括で書き換えます
• plugin sync を実行して appkit.plugins.json を更新します

オプション:

• --dry-run -- 書き込みを行わず、変更内容のみを表示します
• --skip-imports -- マニフェストのみを更新します
• --skip-sync -- sync を自動実行しません
• --allow-installed -- node_modules 配下にのみ存在する plugin の昇格を許可します (上級者向け)

マニフェストフィールド

manifest.json の stability フィールドは任意です。指定がない場合、その plugin は GA として扱われます。

{
  "name": "my-plugin",
  "displayName": "My Plugin",
  "description": "An in-development feature",
  "stability": "beta",
  "resources": { "required": [], "optional": [] }
}

有効な値: "beta"、"ga"。

テンプレートマニフェスト (appkit.plugins.json)

plugin sync は、GA ではない plugin を検出すると、その安定性を出力に含めます。これは すべての 検出経路に当てはまります。サーバーファイルから解決された plugin、--plugins-dir やローカルの plugin ツリーから解決された plugin、node_modules 配下の既知のパッケージ (例: @databricks/appkit) から解決された plugin のいずれも対象です。各 plugin の manifest.json に記載されたティアは、GA でない限り、同期されたテンプレートマニフェストに必ず反映されます。

{
  "version": "1.1",
  "plugins": {
    "my-plugin": {
      "name": "my-plugin",
      "stability": "beta",
      "package": "@databricks/appkit"
    }
  }
}

requiredByTemplate を指定できるのは GA plugin のみです。GA 以外の plugin は、init 時には常に任意扱いとなります。

サードパーティ製pluginの作者向け

インポートパス (/beta) が適用されるのは、@databricks/appkit に同梱されるファーストパーティ製pluginのみです。サードパーティ製pluginは、manifest.json の stability フィールドで安定性を宣言します。CLI ツール (plugin list、plugin sync) は、この情報をユーザーに提示します。

ファーストパーティ plugin 作成者向け (AppKit モノレポ)

AppKit モノレポ内では、各 plugin の manifest.json の stability フィールドが、その plugin をどのサブパスでリリースするかを決める唯一の信頼できる情報源です。2 つのビルド時ジェネレーターが、すべての packages/appkit/src/plugins/<name>/manifest.json を読み取ります:

• tools/generate-plugin-entries.ts は runtime のエクスポートバレルを生成します:
  • packages/appkit/src/plugins/ga-exports.generated.ts — GA plugin の再エクスポート。src/index.ts (@databricks/appkit エントリ) に含まれます。
  • packages/appkit/src/plugins/beta-exports.generated.ts — beta plugin の再エクスポート。src/beta.ts (@databricks/appkit/beta エントリ) に含まれます。
• tools/generate-plugin-doc-banners.ts は、各 plugin のドキュメントページ (docs/docs/plugins/<name>.md) の先頭に :::warning Beta plugin の注意書きを挿入 (または削除) し、ドキュメント上の安定性がマニフェストに追従するようにします。このスクリプトが書き込むのは docs/docs/plugins/ 配下のみです: 各マニフェストの name は plugin スキーマのパターン (^[a-z][a-z0-9-]*$) に一致している必要があり、解決後のドキュメントパスも検証されるため、不正な形式の name によってこのディレクトリの外に書き込まれることはありません。

生成された成果物はすべてコミットされ、CI で検証されます。内容が最新でないファイルがあると、Check generated types are up to date ステップが失敗します。

appkit plugin promote コマンドはモノレポのコンテキスト (tools/generate-plugin-entries.ts の有無) を検出し、マニフェストの更新後にジェネレーターを再実行します。そのため、runtime のエクスポート、同期された appkit.plugins.json、マニフェストの内容が食い違うことはありません。

組み込み plugin を手動で別のティアへ移動するには:

# packages/appkit/src/plugins/<name>/manifest.json を編集
# "stability": "beta" を設定（GA の場合はこのフィールドを削除）
pnpm run generate:types   # スキーマ/レジストリの型、エクスポートバレル、ドキュメントのバナーを再生成
pnpm sync:template        # template/appkit.plugins.json を再生成