コンポーネントとレジストリ

Atlas がコンポーネントをウェブサイトに配布することは決してありません。コンポーネントはお客様のリポジトリに残ります。サイトコントラクトが、どのコンポーネントが存在し、編集者がどのフィールドに入力できるかを Atlas に伝えます。

コンポーネントの宣言方法

コントラクト内の各コンポーネントには、次のものがあります。

• acme.home.hero のような修飾付き IDと、バージョン。
• 種別: section、block、layout のいずれか。
• 型付きフィールド。たとえば heading（テキスト、必須、80 文字まで）、image（アセット）、cta（リンク）。

編集者には、これらのフィールドから作られたフォームが表示されます。フィールドの追加、HTML の貼り付け、マークアップの変更はできません。

ウェブサイトでの表示方法

各コンポーネント ID を、それを表示する React コンポーネントに対応づける小さなレジストリをコード内に置きます。

atlas/sections.tsx

import { Hero } from '@/components/hero';
import { FeatureGrid } from '@/components/feature-grid';
import type { AtlasSection } from '@/lib/atlas';

const registry = {
  'acme.home.hero': Hero,
  'acme.home.features': FeatureGrid,
} as const;

export function renderSection(
  section: AtlasSection,
  assets: Record<string, { url: string; alt?: string }>,
) {
  const Component = registry[section.component.id as keyof typeof registry];
  if (!Component) return null; // unknown component: skip it, never guess
  return <Component key={section.id} {...section.props} assets={assets} />;
}

コンポーネントが受け取る props は、他の外部入力を検証するのと同じ方法で検証してください。

コードとコンテンツの同期を保つ

ウェブサイトは、起動時に自分が構築されたときのコンポーネントを報告します（POST /deployments）。Studio はそれを有効なコントラクトと比較し、次のいずれかを表示します。

状態	意味
In sync	デプロイ済みのビルドが、有効なコントラクトを表示できる
Missing components	コントラクトが、このビルドにないコンポーネントを使っている。先にコードをデプロイしてください
Different contract	ビルドがコントラクトの別のバージョン向けに作られている
Unknown contract	このビルドが報告するコントラクトを、Atlas が一度も見ていない
No contract	有効なコントラクトがまだない

ウェブサイトが同期していない間は、本番リリースを承認できません。これにより、稼働中のサイトにまだ存在しないコンポーネントを編集者が使うことを防ぎます。

新しいコンポーネントを追加する

1. ウェブサイトのコードでコンポーネントを構築してテストします。
2. フィールドとともにコントラクトバンドルに追加し、編集者が挿入できるページタイプにも追加します。
3. コントラクトを検証して提案します。サイト管理者が有効化します。
4. ウェブサイトをデプロイします。Studio に In sync と表示されます。
5. これで、編集者がそのコンポーネントを使えます。