custom-pages-and-apis

EventCatalog カスタムページと API

EventCatalog 自体から配信される、ユーザー定義のページと API ルートを作成できます。安定した、ドキュメント化されたツールキットを通じて、カタログデータ（ドメイン、サービス、イベント、チームなど）にフルアクセスできます。

カスタムページはカタログルートの pages/ フォルダーに配置され、設定可能な URL プレフィックス（デフォルトは /custom）の下で配信されます。API ルートは pages/api/ に配置し、SSR モードが必要です。

要件（まず最初に確認してください）

ファイルを作成する前に、次の両方を確認してください。

1. Core のバージョン — @eventcatalog/core 5.0.0 から、すべてのカタログでカスタムページが配信されます（プランやライセンスキーは不要です）。4.1.0～4.x のバージョンでは、Scale ライセンスキーがある場合に限り配信されていました。また、Layout の fullWidth プロパティには 4.12 以降が必要です。カタログの package.json を確認し、4.x の場合はアップグレードを提案してください。
2. API ルートのみ SSR が必要 — .astro ページはどの出力モードでも動作しますが、pages/api/ 以下に配置するものには eventcatalog.config.js で output: "server" を指定する必要があります。API ルートが静的モードで存在すると、本番ビルドはハードエラーで失敗します（開発時は警告のみです）。references/api-routes.md を参照してください。

手順

ステップ 1：カタログを特定する

ユーザーの EventCatalog プロジェクトを探します（eventcatalog.config.js を探してください）。次に、以下を確認します。

• すでに pages/ が存在しますか？ 中身を確認してください。pages/homepage.astro も確認します。これは特殊なファイルで、カタログのホームページ（/）を置き換え、プレフィックスの下では配信されません。このファイルがない場合、カタログには組み込みのダッシュボードホームページが表示されます。
• 設定されているプレフィックスは何ですか？ eventcatalog.config.js の pages.prefix を確認します（デフォルトは custom）。生成するすべてのリンクでこれを使用してください。
• 設定されている出力モード（output: "static" または "server"）は何ですか？
• カタログに components/ フォルダーはありますか？ その中のファイルは @catalog/components/* としてインポートできます。
• eventcatalog.config.js で landingPage が設定されていますか？ 設定されている場合、/ はそこにリダイレクトされ、カスタムホームページは表示されません。

ステップ 2：ユーザーが作成したいものを把握する

よくある要望と、その作成先は次のとおりです。

ユーザーの要望	作成するファイル	URL
コンテンツ／ダッシュボードページ	pages/reports.astro	/custom/reports
カスタムホームページ	pages/homepage.astro	/（デフォルトのホームページを置き換え）
インデックス付きのセクション	pages/tools/index.astro	/custom/tools
動的ページ	pages/reports/[id].astro	/custom/reports/:id
JSON API エンドポイント	pages/api/stats.ts	/custom/api/stats
動的 API エンドポイント	pages/api/teams/[id].ts	/custom/api/teams/:id
共有パーシャル／コンポーネント	pages/_components/Card.astro	ルートとして扱われません（アンダースコアのプレフィックス）

ルーティングの詳細なルール（拡張子、インデックスの扱い、アンダースコア規約、予約済みプレフィックス、プレフィックスの検証）については、references/routing.md を参照してください。

カスタムホームページ： pages/homepage.astro はすでに EventCatalog のシェル内でレンダリングされるため、Layout でラップしないでください。Astro.props.components で EventCatalog のコンポーネントを受け取ります。これには、デフォルトのダッシュボードである CatalogDashboard（title と description は任意）が含まれるため、ホームページを作り直すのではなく、ダッシュボードにコンテンツを追加できます。

---
const { CatalogDashboard } = Astro.props.components;
---

<div class="not-prose">
  <CatalogDashboard title="Acme Catalog" description="Our domains, systems, services and messages." />
</div>

ステップ 3：ツールキットでページを構築する

EventCatalog の内部実装より、常に安定した公開ツールキットを優先してください。

• @catalog/layouts/Layout.astro — EventCatalog のページシェル（ヘッダー、ナビゲーション、オプションのリソースサイドバー）です。Props：title（必須）、description?、sidebar?（デフォルトは true）、showHeader?（デフォルトは true）、fullWidth?（デフォルトは false。EventCatalog のページパディングなしで画面端まで表示します。独自のレイアウトを制御するページ向けです）。
• @catalog/utils — キャッシュされたコレクション取得関数：getDomains、getServices、getSystems、getEvents、getCommands、getQueries、getFlows、getChannels、getEntities、getAgents、getContainers、getDataProducts、getAdrs、getTeams、getUsers、および semver 解決用の getItemsFromCollectionByIdAndSemverOrLatest です。最新バージョンのみ取得するには、{ getAllVersions: false } を渡します。
• @catalog/components/* — ユーザーのカタログの components/ フォルダーにある独自のコンポーネントです。

最小限のページ：

---
import Layout from '@catalog/layouts/Layout.astro';
import { getServices } from '@catalog/utils';

const services = await getServices({ getAllVersions: false });
---

<Layout title="Service Report" description="All services in our architecture" sidebar={false}>
  <div class="max-w-4xl mx-auto p-8">
    <h1 class="text-2xl font-bold text-[rgb(var(--ec-page-text))]">Services ({services.length})</h1>
    <ul>
      {services.map((service) => (
        <li>
          <a href={`/docs/services/${service.data.id}/${service.data.version}`}>{service.data.name}</a>
        </li>
      ))}
    </ul>
  </div>
</Layout>

ページコードを生成する際の主な規約：

• Tailwind はそのまま使えます。 色には EventCatalog のテーマ変数を使用し、ページがライト／ダークモードに対応するようにしてください：text-[rgb(var(--ec-page-text))]、bg-[rgb(var(--ec-page-bg))]、border-[rgb(var(--ec-page-border))]、bg-[rgb(var(--ec-card-bg))]、text-[rgb(var(--ec-accent))]。dark: バリアントは使用しないでください。
• コレクションのエントリーは Astro のコンテンツエントリーです。データは entry.data にあります（例：entry.data.id、entry.data.name、entry.data.version、entry.data.summary）。エントリー ID は {id}-{version} の形式です。
• カタログのドキュメントページへのリンクは /docs/{collection}/{id}/{version} にします（例：/docs/services/OrderService/1.0.0）。チームとユーザーにはバージョンがないため、/docs/teams/{id}、/docs/users/{id} を使用します。リソースの一覧は /discover/{type} にあります（例：/discover/services、/discover/events）。
• owners とチームの members は参照（{ id, collection }）であり、エントリー全体ではありません。名前を表示するには、getTeams()／getUsers() で ID を検索してください。
• 共通のパーシャルは pages/_components/ に配置し、相対パスでインポートしてください。
• EventCatalog の内部実装（@components/*、@utils/*、@layouts/*）からインポートしないでください。解決はされますが、安定した契約ではないため、リリースのたびに動作しなくなる可能性があります。公開 API は @catalog/* のみです。

ツールキットの完全なリファレンス（すべての取得オプション、Layout の Props、エントリーの形状）：references/toolkit.md。 動作する完全なサンプル（外部データの取得、動的ルート、ナビゲーションのパーシャル、API エンドポイント）：references/examples.md。

ステップ 4：ページをナビゲーションに追加する

ページには URL からすぐにアクセスできますが、通常は垂直ナビゲーションにも追加します。eventcatalog.config.js の navigation.groups にグループを追加してください。ただし、groups を指定するとデフォルトのナビゲーション全体が置き換わるため、引き続き表示したい組み込み項目も含めてください。

navigation: {
  groups: [
    { id: 'main', items: [{ id: 'home' }, { id: 'docs' }] },
    { id: 'browse', label: 'Browse', items: [{ id: 'catalog' }, { id: 'schemas' }] },
    {
      id: 'my-pages',
      label: 'My Company',
      items: [
        { id: 'reports', label: 'Reports', href: '/custom/reports', icon: 'ChartBar' },
        { id: 'team', label: 'Our Team', href: '/custom/team', icon: 'UsersRound' },
      ],
    },
    { id: 'settings-group', position: 'bottom', items: [{ id: 'settings' }] },
  ],
}

• 組み込み項目の ID：home、docs、catalog、schemas、schema-insights、teams、users、settings、studio。
• カスタム項目には href が必要です。icon には lucide-react のアイコン名を指定します（例：Workflow、Github、ChartBar）。
• 子ルートでも項目がハイライト表示されるようにするには、match（文字列または配列）を使用します（例：match: '/custom/reports'）。照合は単純なプレフィックスチェック（グロブなし）のため、/custom/reports/2024 も対象になります。
• 設定に navigation.groups がまだなく、ユーザーがリンクを 1 つ追加したいだけの場合は、デフォルトのナビゲーションを置き換える前に確認してください。または、ナビゲーションへの追加は行わず、URL のみを共有してください。

ステップ 5：エディターのサポート（推奨）

VS Code は最も近い tsconfig.json を基準にインポートを解決するため、tsconfig.json がないと @catalog/* のインポートに「モジュールが見つかりません」という警告が表示されます（ビルドは引き続き動作します。エイリアスは実行時に EventCatalog が解決します）。カタログのルートに tsconfig.json を作成し、インストール済みの @eventcatalog/core パッケージ内のツールキットを指定してください。

{
  // Editor support (IntelliSense, go-to-definition) for custom pages.
  // These aliases mirror the ones the EventCatalog build provides at runtime.
  "compilerOptions": {
    "baseUrl": ".",
    "allowJs": true,
    "jsx": "preserve",
    "paths": {
      "@catalog/components/*": ["components/*", "federated/components/*"],
      "@catalog/layouts/*": ["node_modules/@eventcatalog/core/eventcatalog/src/toolkit/layouts/*"],
      "@catalog/utils": ["node_modules/@eventcatalog/core/eventcatalog/src/toolkit/utils/index.ts"],
      "@catalog/utils/*": ["node_modules/@eventcatalog/core/eventcatalog/src/toolkit/utils/*"]
    }
  },
  "include": ["pages/**/*", "components/**/*"]
}

注：以前のガイドでは、これらのパスに .eventcatalog-core/ を指定していましたが、EventCatalog は 4.12 以降、このディレクトリを生成しなくなりました。カタログに古いパスを指定した tsconfig.json がある場合は、更新してください。このファイルを追加した後、TS／Astro 言語サーバーを再読み込みするようユーザーに伝えてください。

ステップ 6：確認

1. 開発サーバーを起動します（npm run dev）。すでに実行中の場合は再起動は不要です。EventCatalog は pages/ フォルダーを監視し、新規ファイルや削除されたファイルを自動的に検出します（ファイルの追加／削除時にはサーバーが短時間自動的に再起動し、編集内容はホットリロードされます）。
2. プレフィックス付き URL（例：http://localhost:3000/custom/reports）でページを開き、EventCatalog のシェル内に表示されることを確認します。
3. API ルートの場合は、エンドポイントに curl を実行して JSON レスポンスを確認します。
4. ページが 404 になる場合は、次の順に確認します。URL のプレフィックスは正しいですか？ファイルの拡張子はルーティング可能なもの（.astro、.ts、.js、.mjs）ですか？アンダースコアで始まるフォルダー内にありませんか？

トラブルシューティング

症状	原因
すべてのカスタムページが 404 になり、Custom pages require the Scale plan という警告が表示される	カタログが Scale キーなしで @eventcatalog/core 4.x を使用しています。すべてのカタログでカスタムページが提供される 5.x にアップグレードしてください
ビルドエラー：API ルートには output: "server" が必要	pages/api/** が存在しますが、設定が静的です。output: "server" を設定するか、API ルートを削除してください
ページが 404 になるが、ほかのページは表示される	アンダースコアで始まるパスのセグメント、ルーティングできない拡張子、または誤ったプレフィックス
エディターのみで Cannot find module '@catalog/utils' が表示される	カタログレベルの tsconfig.json がありません（ステップ 5）。ビルドへの影響はありません
設定エラー：pages.prefix ... is reserved	プレフィックスがコアのルートと衝突しています。references/routing.md の予約済みリストを参照してください
pages/homepage.astro の追加後もホームページが変わらない	eventcatalog.config.js で landingPage が設定されています（最初に / へリダイレクトします）。または、プレフィックス配下を表示しています。ホームページは / で提供されます
ホームページにヘッダーが 2 つ表示される／ナビゲーションが入れ子になる	homepage.astro が Layout でラップされています。削除してください。ホームページはすでにシェル内でレンダリングされています
.json ファイルに対して予期しないルートまたはルートエラーが発生する（例：pages/data.json → /custom/data）	pages/ 内の .json ファイルはルートとして検出されます。データファイルはアンダースコアで始まるフォルダー（pages/_data/）に置いてください

リファレンスファイル

• references/routing.md — ファイルから URL へのマッピング、プレフィックスの設定と検証、予約済みプレフィックス、アンダースコアの規則、homepage.astro
• references/toolkit.md — @catalog/layouts、@catalog/utils、@catalog/components の詳細
• references/api-routes.md — API エンドポイント、SSR 要件、レスポンスパターン
• references/examples.md — カスタマイズ可能な動作する完全な例