using-backstage-frontend-system

Backstage New Frontend System（NFS）のパターン

このスキルを使用する場面

• 新しいフロントエンドプラグインを定義する（src/plugin.tsx）
• ルート参照を宣言する（src/routes.ts）
• プラグインから API を公開する（src/apis.ts）
• ページ、サブページ、その他のエクステンションを追加する（src/extensions.tsx）
• NFS のフックを使用する（useApi、useRouteRef）

適切なパターンを選ぶ

構築するもの	パターン	リファレンス
プラグイン自体	createFrontendPlugin({ pluginId, ..., extensions })	references/plugin-definition.md
ルート参照	@backstage/frontend-plugin-api の createRouteRef、createSubRouteRef、createExternalRouteRef	references/route-refs.md
バックエンドエンドポイントの呼び出し（デフォルト）	fetchApi.fetch を呼び出す useAsync／useAsyncFn をラップしたデータフック — クライアントクラスもエクステンションも不要	references/api-extensions.md
オープンソースプラグインで拡張可能な API を公開する	ApiBlueprint.make({ params })	references/api-extensions.md
ページ（単一ルート）	PageBlueprint.make({ params: { path, routeRef, loader } })	references/page-extensions.md
タブ付きページ	PageBlueprint（ローダーなし）＋ SubPageBlueprint	references/sub-pages.md
コンポーネントで API を読み取る	@backstage/frontend-plugin-api の useApi(apiRef)、useRouteRef(routeRef)	references/hooks.md

2 つの呼び出しモード

• スタンドアロン：ユーザーが既存の NFS プラグインを編集中の場合です。リファレンスを選んで適用します。
• スキャフォールド後（frontend-plugin／frontend-plugin-module テンプレートで creating-backstage-plugin から呼び出される場合）：新しくスキャフォールドされたプラグインに標準的な NFS 構造を組み込みます — src/routes.ts、createFrontendPlugin を使用する src/plugin.tsx、および PageBlueprint エクステンションの例です。

よくある注意点

• NFS では、プラグインシステムのインポート元は @backstage/core-plugin-api ではなく @backstage/frontend-plugin-api です。フック（useApi、useRouteRef）、参照（identityApiRef、configApiRef、discoveryApiRef、fetchApiRef、storageApiRef、analyticsApiRef）、プリミティブ（createApiRef）はすべて新しいパッケージにあります。
• createRouteRef() に id 引数は不要です。id は、そのルートを所有するエクステンションから導出されます。
• createExternalRouteRef({ defaultTarget: '<pluginId>.<routeName>' }) では、最も一般的なバインディングを defaultTarget に設定してください。これにより、アプリで明示的な bindRoutes の呼び出しが不要になります。
• 外部ルートがバインドされていない場合、useRouteRef(externalRef) は undefined を返すことがあります。必ず undefined の場合を処理してください。
• PageBlueprint のローダー内のページコンポーネントに、@backstage/core-components の Page、Header、PageWithHeader を含めないでください。フレームワークの PageLayout が PluginHeader を自動的に描画します。ページコンテンツの最外部のラッパーには、@backstage/ui の Container を使用してください。サブタイトルやカスタムアクションが必要な場合に限り、@backstage/ui の Header を使用してください。
• SubPageBlueprint のパスは相対パスです（先頭に / は付きません）。サブページコンポーネントはコンテンツのみを描画し、Page、Header、HeaderTabs は含めません。パディングが必要な場合は、サブページのコンテンツを @backstage/ui の Container で囲んでください。
• createApiRef<T>().with({ id, pluginId }) では、所有権が明示されるためビルダー形式が推奨されます。id は引き続きグローバルに一意である必要があります。API をオーバーライドできるのは、所有するプラグイン（またはそのプラグインを対象とするモジュール）だけです。
• fetchApi.fetch の呼び出しでは、@backstage/errors の throw await ResponseError.fromResponse(response) を使用して、OK 以外のレスポンスを処理してください。レスポンスボディを解析して構造化されたエラー情報を取り出し、他の Backstage UI サーフェス（例：<ResponseErrorPanel>）が理解できる型付きエラーを生成します。throw new Error(\Failed: ${response.status}`)` のように単純にエラーをスローしないでください。