プラグインの管理

AppKit には plugin を管理するための CLI が含まれています。すべてのコマンドは npx @databricks/appkit plugin 配下で利用できます。

マニフェストの規約: CLI コマンド (sync、list、validate) では manifest.json がデフォルトかつ推奨のフォーマットです。ゼロトラストの観点から、JS マニフェスト (manifest.js / manifest.cjs) は --allow-js-manifest を指定しない限り無視されます。このオプションは plugin のコードを実行するため、信頼できるソースに対してのみ使用してください。add-resource コマンドは manifest.json のみをその場で編集します。

pluginを作成する

対話形式またはフラグ指定で、新しいpluginをスキャフォールディングします。

# 対話モード（すべてのオプションを対話形式で入力）
npx @databricks/appkit plugin create

# 非対話モード（必須フラグをすべて指定）
npx @databricks/appkit plugin create \
  --placement in-repo \
  --path plugins/my-plugin \
  --name my-plugin \
  --description "My custom plugin" \
  --resources sql_warehouse \
  --force

対話モードでは、ウィザードが次の手順を案内します。

配置場所: リポジトリ内 (例: plugins/my-plugin) か、スタンドアロンパッケージとして
メタデータ: 名前、表示名、説明
リソース: plugin が必要とする Databricks リソース (SQL Warehouse、Secret など) と、それぞれが必須か任意か

非対話モードでは、--placement、--path、--name、--description が必須です。リソースはカンマ区切りのリスト (--resources sql_warehouse,volume) で指定するか、細かく制御したい場合は JSON (--resources-json '[{"type":"sql_warehouse","permission":"CAN_MANAGE"}]') で指定します。利用可能なオプションの一覧は npx @databricks/appkit plugin create --help で確認できます。

このコマンドは、manifest.json と、そのマニフェストを直接インポートする TypeScript の plugin クラスを備えた完全な plugin スキャフォールディングを生成します。そのままアプリに登録できる状態です。

pluginマニフェストを同期する

プロジェクトをスキャンしてpluginを検出し、appkit.plugins.json を生成します。

npx @databricks/appkit plugin sync --write

このコマンドは、インストール済みパッケージとローカルインポートから plugin マニフェストを検出し、deployment ツールが使用する統合マニフェストを出力します。createApp({ plugins: [...] }) の呼び出しで参照されている plugin は、自動的に必須としてマークされます。

信頼済みのインストール済み Databricks パッケージ (例: @databricks/appkit) は、plugin sync の実行中にバンドルされた JS マニフェストを読み込めます。それ以外のソースについては、意図的に JS マニフェストを利用する場合、明示的にオプトインしてください。

npx @databricks/appkit plugin sync --write --allow-js-manifest

ビルドフックで出力を抑制するには、--silent フラグを使用します。

{
  "scripts": {
    "sync": "appkit plugin sync --write --silent",
    "predev": "npm run sync",
    "prebuild": "npm run sync"
  }
}

マニフェストを検証する

pluginのマニフェストをJSONスキーマに照らして検証します。

# カレントディレクトリの manifest.json を検証
npx @databricks/appkit plugin validate

# 特定のファイルまたはディレクトリを検証
npx @databricks/appkit plugin validate plugins/my-plugin appkit.plugins.json

バリデーターは、対象ファイルが plugin マニフェストかテンプレートマニフェストかを $schema から自動判別し、読みやすいパス表記と期待値を添えてエラーを報告します。

JS マニフェストも validation の対象に含めるには、--allow-js-manifest を指定します。

pluginの一覧表示

appkit.plugins.json に登録されているpluginを表示するか、ディレクトリをスキャンします:

# appkit.plugins.json から取得（デフォルト）
npx @databricks/appkit plugin list

# ディレクトリをスキャンして plugin フォルダーを検索
npx @databricks/appkit plugin list --dir plugins/

# ディレクトリをスキャンし、JS マニフェストも含める（信頼できるコードのみ）
npx @databricks/appkit plugin list --dir plugins/ --allow-js-manifest

# スクリプト向けの JSON 出力
npx @databricks/appkit plugin list --json

plugin へのリソースの追加

既存の plugin マニフェストに新しいリソース要件を追加します。plugin ディレクトリに manifest.json が必要です (コマンドは既存のファイルを直接編集し、manifest.js は変更しません) :

# 対話モード
npx @databricks/appkit plugin add-resource
npx @databricks/appkit plugin add-resource --path plugins/my-plugin

# 非対話モード（--type を指定するとフラグベースのモードになる）
npx @databricks/appkit plugin add-resource --path plugins/my-plugin --type sql_warehouse
npx @databricks/appkit plugin add-resource --path plugins/my-plugin --type volume --no-required --dry-run

非対話モードで必須なのは --type のみです。その他のフィールド (権限、リソースキー、フィールドの環境変数) には、スキーマに基づく妥当な値がデフォルトで設定されます。マニフェストに書き込まずに更新内容をプレビューするには --dry-run を使用してください。利用可能なオプションの一覧は、npx @databricks/appkit plugin add-resource --help を実行して確認できます。