using-backstage-ui

Backstage UI（BUI）のパターン

このスキルを使うタイミング

• Backstage プラグインのフロントエンドコンポーネントを作成または編集するとき
• レイアウト、タイポグラフィ、フォーム入力、ダイアログ、メニュー、タブ、テーブルなどに適したコンポーネントを選ぶとき
• コンポーネントをスタイル設定するとき（BUI では makeStyles ではなく、CSS モジュールとデザイントークンを使用します）
• アイコンを追加するとき（@remixicon/react を使用します）

セットアップ

yarn new で新しいプラグインのスキャフォールドを作成すると、@backstage/ui が自動的に含まれます。手動でインストールする場合：

yarn add @backstage/ui @remixicon/react

次に、スタイルシートをアプリのエントリポイント（packages/app/src/index.tsx など）に追加します。

import '@backstage/ui/css/styles.css';

適切なコンポーネントを選ぶ

必要なもの	コンポーネント	参照
ページレイアウト／ラッパー	Box、Container、Flex、FullPage、Grid	references/components.md
タイポグラフィ	Text	references/components.md
ボタン／アクション	Button、ButtonIcon、ButtonLink	references/components.md
フォーム	TextField、PasswordField、SearchField、Select、Combobox、Checkbox、RadioGroup、Switch、DatePicker、DateRangePicker	references/components.md
フィードバック	Alert、Skeleton、Tooltip、Tag、TagGroup	references/components.md
オーバーレイ	Dialog、Menu、Popover	references/components.md
ナビゲーション	Tabs、Header、PluginHeader、Link	references/components.md
データ	Table（＋useTable フック）、List（＋ListRow）、Avatar、Card	references/components.md
アイコン	@remixicon/react（例：RiSearchLine、RiAddLine）	references/icons.md
スタイル設定	BUI トークン（--bui-space-*、--bui-fg-*、--bui-bg-*）を使った CSS モジュール	references/styling.md

2 つの呼び出しモード

• 単独（開発中）：ユーザーが既存のプラグインコンポーネントを編集しています。関連するリファレンスを選んで適用します。
• スキャフォールド後（フロントエンドテンプレートの場合に creating-backstage-plugin から呼び出される）：スキャフォールド直後のプラグインのサンプルコンポーネントに BUI のデフォルトを適用し、インポート元が @backstage/ui で、スタイルに BUI トークンを使った CSS モジュールが使用されるようにします。

よくある注意点

• BUI は Material UI とは異なります。プロパティ名を混同しないでください。disabled → isDisabled、variant="contained" → variant="primary" です。
• Flex では justify="between" を使います（space-between ではありません）。gap はインラインの style または BUI トークンで指定します。
• Tooltip は親要素として TooltipTrigger が必要です。
• TextField の onChange には、イベントオブジェクトではなく文字列が直接渡されます。
• BUI に相当するものがない既知の例外が 1 つあります。@material-ui/lab の Timeline に BUI の代替はありません。この場合に限り、MUI を使用してください。

データ取得の規約

ローディング／エラー／データの状態を管理するために、useState を手動で組み合わせないでください。react-use のフックを使います。

• useAsync(fn, deps) — マウント時と deps の変更時に、非同期関数を実行します。「コンポーネントのレンダリング時や props の変更時にデータを読み込む」場合に使います。
• useAsyncFn(fn) — [state, callback] を返します。「ユーザーが操作したとき（ボタンのクリック、フォームの送信など）にデータを読み込む」場合に使います。

{ loading, error, value } を管理するために useState を手動で使うのは、このコードベースではアンチパターンです。フックが適切に処理するロジック（競合状態、フェッチ中のアンマウントなど）を重複させるためです。カタログと ID の参照例では useAsync を使っています。データを取得する箇所では、同様に適用してください。

import useAsyncFn from 'react-use/lib/useAsyncFn';
import { Button, Skeleton, Alert, Text } from '@backstage/ui';

export const FetchOnDemand = () => {
  const [{ loading, error, value }, fetch] = useAsyncFn(async (id: string) => {
    return await someApi.get(id);
  }, []);

  return (
    <>
      <Button onClick={() => fetch('foo')}>Fetch</Button>
      {loading && <Skeleton width={200} height={20} />}
      {error && <Alert status="danger" title={error.message} />}
      {value && <Text>{value.name}</Text>}
    </>
  );
};