creating-backstage-plugin

Backstage プラグインの作成

このスキルを使用するタイミング

ユーザーが Backstage リポジトリで新しいプラグインを作成しようとしています。次のいずれかに該当します。

• プラグインについて自由記述で説明している（「グループを一覧表示するフロントエンドプラグインが欲しい」など）
• または、一般的な依頼をしていて（「新しいプラグインをひな形から作成して」など）、ユーザーに希望を確認する必要がある

手順

必ず以下の手順を順番に実行してください。手順 3 でユーザーが計画を承認するまでは、yarn new を実行しないでください。

1. 意図を把握する

ユーザーがプラグインについてすでに説明している場合は、その内容を解析します。そうでなければ、次の質問を 1 つだけ尋ねます。

「どのようなプラグインが必要で、何をするものですか？」

2. 意図を計画にまとめる

ユーザーの説明を次の項目に対応付けます。

• packages: 1 つ以上のパッケージのひな形。ほとんどのプラグインは単一のパッケージですが、接続されたプラグイン（専用のバックエンドを呼び出すフロントエンド）には、frontend-plugin、backend-plugin、共有型用の plugin-common-library の 3 つが必要です。これを提案する条件については、以下の「接続されたプラグインのセット」を参照してください。
• template（パッケージごと）：サポートされている 9 種類のテンプレートのいずれか（一覧と選択ルールについては references/templates.md を参照してください）。
• id（パッケージごと）：ケバブケース。接続されたセットでは、3 つの ID に共通のベースを使用します（例：jira、jira-backend、jira-common）。
• patterns（パッケージごと）：ひな形作成後に呼び出すパターンスキル。キーワードからパターンを判断するヒューリスティックについては、references/intent-detection.md を参照してください。

接続されたプラグインのセット

ユーザーが、UI と専用バックエンドの両方を持つプラグインについて説明している場合（例：「プロジェクト情報を表示する Jira プラグイン」→ Jira API 呼び出しを仲介するバックエンドと、その結果を表示するフロントエンドが必要）、単一のテンプレートではなく、3 パッケージのセットを提案します。

パッケージ	テンプレート	目的
<id>	frontend-plugin	UI
<id>-backend	backend-plugin	バックエンドのルート。上流システムと通信します
<id>-common	plugin-common-library	両側でインポートする共有 TypeScript 型（リクエスト／レスポンスのインターフェース、ドメインモデル）

該当する条件（いずれかに当てはまれば 3 パッケージのセットを提案します）。

• プラグインの説明に、認証済みまたはサーバーサイドの呼び出しが必要な外部システムが含まれている（Jira、ServiceNow、PagerDuty、ブラウザーに公開されていない内部 API など）
• ユーザーの説明で「 からの X を表示するページ」とされていて、X にバックエンドでの計算、シークレット、またはクライアント側には適さないページネーション／集計が必要
• ユーザーが明示的に「フロントエンドとバックエンドの両方」を求めている、または両方について言及している

次の場合は 3 パッケージを提案しないでください。

• プラグインが、すでにインストール済みの Backstage バックエンド（カタログ、scaffolder など）から読み取るだけの場合。既存のサービス参照で対応できるため、カスタムバックエンドは不要です
• プラグインが表示のみを目的としている場合（フォーム、計算機、静的データのダッシュボード）

3 パッケージのセットを提案する場合は、手順 3 の確認メッセージに 3 つすべてを記載し、ユーザーが変更できるようにしてください（例：「実際にはフロントエンドだけでよく、バックエンドはすでにあります」）。3 つのパッケージのうち、すでにユーザーが持っているものがある場合は、不足しているものだけをひな形から作成します。

3. ユーザーに確認する

次の形式で構造化された概要を表示し、明示的な承認を待ちます。

I'll scaffold a `<template>` named `<id>` and wire up:
- <pattern 1 description>
- <pattern 2 description>

Sound right, or want to adjust?

ユーザーが変更を希望する場合は、内容を修正して再確認します。

4. yarn new を実行する

確認が取れたら、計画に含まれる各パッケージについて、リポジトリのルートから実行します。

単一パッケージの場合（プラグイン、ライブラリ）：

yarn new --select <template> --option pluginId=<id>

モジュールの場合（backend-plugin-module、frontend-plugin-module）— モジュールにはホストプラグイン ID とモジュール ID の両方が必要です。

yarn new --select backend-plugin-module --option pluginId=<host-plugin> --option moduleId=<module-id>

たとえば、カタログプロセッサーモジュールの場合：

yarn new --select backend-plugin-module --option pluginId=catalog --option moduleId=my-processor

これにより、plugins/catalog-backend-module-my-processor が作成されます。

連携するプラグインセットの場合 — 3 つのコマンドを順番に実行します（他のプラグインが依存できるよう、最初に -common を実行します）。

yarn new --select plugin-common-library --option pluginId=<id>-common
yarn new --select backend-plugin --option pluginId=<id>
yarn new --select frontend-plugin --option pluginId=<id>

注：yarn new --select backend-plugin --option pluginId=<id> を実行すると、plugins/<id>-backend が作成されます（テンプレートによって -backend サフィックスが追加されます）。フロントエンドでは plugins/<id> が作成されます。common では plugins/<id>-common が作成されます。

yarn new の実行後、毎回ディレクトリを確認します。

ls plugins/<id-or-suffix>

ディレクトリが存在しない場合は処理を中止し、エラーをユーザーに伝えてください。

5. スキャフォールド後にパターンを適用する

計画に含まれる各パターンについて、Skill ツールを使って対応するパターンスキルを呼び出します。新しいプラグイン ID と、スキャフォールド後の呼び出しであることを示す指示を渡します。各パターンスキルのリファレンスには、ファイル名と挿入位置を示す「スキャフォールド後の使用」セクションがあります。

フロントエンドテンプレート（frontend-plugin、frontend-plugin-module）：

• using-backstage-frontend-system — 必ず呼び出します。標準の NFS 構造（src/routes.ts、createFrontendPlugin を使用する src/plugin.tsx、サンプルの PageBlueprint）を組み込みます。
• using-backstage-ui — 必ず呼び出します。スキャフォールドで生成された MUI のインポートやスタイリングを、@backstage/ui の同等機能と BUI トークンを使った CSS モジュールに置き換えます。
• using-backstage-catalog — 意図にカタログデータが含まれる場合、（フロントエンドモードで）呼び出します。
• using-backstage-identity — 意図に現在のユーザーが含まれる場合に呼び出します。
• creating-backstage-scaffolder-field — 意図がスキャフォルダーのフォームフィールド／ui:field／カスタムフィールド拡張について説明している場合、frontend-plugin-module に対して呼び出します。
• creating-backstage-entity-page-extension — 意図がカタログエンティティページ上のカードまたはタブについて説明している場合（「コンポーネントページに X を表示する」「Y のカードを追加する」「エンティティページにタブを追加する」）、frontend-plugin-module に対して呼び出します。
• using-backstage-permissions — 意図が権限による UI の表示制御について説明している場合（「管理者にのみ表示する…」「…には権限が必要」「…でない限り、このボタンを非表示にする」）、（フロントエンドモードで）呼び出します。

フロントエンドライブラリ（plugin-web-library）：

• using-backstage-ui — 必ず呼び出します。

バックエンドテンプレート（backend-plugin、backend-plugin-module）：

• using-backstage-backend-system — 必ず呼び出します。createBackendPlugin／createBackendModule を使用する src/plugin.ts または src/module.ts と、再エクスポート用の src/index.ts からなる標準構造を組み込みます。
• using-backstage-backend-services — 必ず呼び出します。coreServices.logger と（プラグインの場合は）coreServices.httpRouter をデフォルトの依存関係として追加します。意図から必要性がうかがえる場合は、追加のサービス（永続化用のデータベース、定期処理用のスケジューラー、プラグイン間呼び出し用の認証など）も追加します。
• using-backstage-catalog — 意図にカタログデータが含まれる場合、（バックエンドモードで）呼び出します。
• using-backstage-permissions — 意図がアクションの認可について説明している場合（「管理者のみ実行できる…」「…には権限が必要」「所有者のみ…」）、（バックエンドモードで）呼び出します。依存関係に coreServices.permissions を追加し、ルートハンドラーに permissions.authorize によるチェックを追加します。

専門分野向けバックエンドテンプレート：

• catalog-provider-module — バックエンドの基盤スキルの後に、creating-backstage-catalog-provider も呼び出します。
• scaffolder-backend-module — バックエンドの基盤スキルの後に、creating-backstage-scaffolder-action も呼び出します。

ライブラリテンプレート（plugin-node-library、plugin-common-library）：自動呼び出しはありません。これらはフレームワークに依存しません。

連携するプラグインセットの場合は、3 つの yarn new コマンドを実行した後に、次を行います。

1. plugins/<id>-common/src/index.ts に、計画で必要とされている共有 TypeScript 型を追加します。-common に含めるもの：

   • ドメインのインターフェースと型エイリアス（例：JiraProject、JiraIssue）
   • バックエンドのルートが返し、フロントエンドのフックが使用するリクエスト／レスポンスの形式
   • バックエンドのルートパスとフロントエンドで共有する定数
   • 必要に応じて、型述語／型ガード
   • Zod スキーマ（両側で同じ形式を検証する場合）

   -common に含めないもの：

   • 実行時の React コードや Express コード
   • @backstage/frontend-plugin-api または @backstage/backend-plugin-api をインポートするもの
   • 副作用を伴う初期化処理

2. フロントエンドとバックエンドの両方の dependencies に、@your/plugin-<id>-common（<id>-common の package.json に記載されたパッケージ名）を追加します。ワークスペース内にあるため、yarn はローカルパッケージを解決します。

3. フロントエンドのデータフック（useJiraProject）で、@your/plugin-jira-common から JiraProject をインポートします。

4. バックエンドのルートハンドラー／サービスで、同じパッケージから同じ型をインポートし、ルートのレスポンス型として使用します。

5. リポジトリのルートから yarn install を実行し、ワークスペースのリンクを設定します。

続いて、フロントエンドとバックエンドに対して、上記のパッケージごとのスキャフォールド後の手順を実行します。

パターンスキルがコードサンプルの管理元です。リファレンスを直接読まないでください。

6. 追加の機能を提案する

パターンを適用した後、最初にユーザーがリクエストしていなかった追加のパターンを提案します。

「プラグインを作成し、<X, Y> を組み込みました。他に追加しますか？（権限、カスタム API、ルート、テストなど）」

ユーザーが追加を希望する場合は、それらのスキルについてステップ 5 を繰り返します。

7. 引き継ぎ

最後に次の概要を出力します。

plugins/<id> にプラグインを作成しました。yarn dev を実行してお試しください。 後からパターンを追加する場合は、using-backstage-frontend-system、using-backstage-backend-system、using-backstage-ui、using-backstage-backend-services、using-backstage-catalog、using-backstage-identity、using-backstage-permissions、creating-backstage-catalog-provider、creating-backstage-scaffolder-action、creating-backstage-scaffolder-field、creating-backstage-entity-page-extension、または（上級者向け）creating-backstage-extension-blueprint を直接呼び出してください。

よくある注意点

• ID はケバブケースにする必要があります。yarn new は Foo や foo_bar を拒否します。
• yarn new を対話形式で実行しないでください。必ず --select と --option pluginId= を指定します。非対話形式で使用するには、両方のフラグが必要です。
• リポジトリが Backstage リポジトリではない場合（ルートに backstage.json がない場合）は、スキャフォールドを開始する前にその旨をユーザーに伝えてください。
• 各パターンスキルは、スキャフォールド直後のプラグインを前提に、スキャフォールド後のモードで動作します。ファイル構成は古い Backstage バージョンとは異なる場合があります。検索はパターンスキルが行うため、ファイルパスを渡さないでください。