컴포넌트와 레지스트리

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. 이제 편집자가 사용할 수 있습니다.