Components and the registry

Atlas never ships components to your website. Your components stay in your repository. The site contract tells Atlas which components exist and which fields editors may fill.

How a component is declared

Each component in the contract has:

• a qualified id, such as acme.home.hero, and a version;
• a kind: section, block or layout;
• typed fields, for example a heading (text, required, up to 80 characters), an image (asset), and a cta (link).

Editors see a form built from those fields. They cannot add fields, paste HTML or change your markup.

How your website renders it

Keep a small registry in your code that maps each component id to the React component that renders it:

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} />;
}

Validate the props your component receives in the same way you would validate any external input.

Keeping code and content in sync

Your website reports the components it was built with when it starts (POST /deployments). Studio compares that with the active contract and shows one of:

State	Meaning
In sync	The deployed build renders the active contract
Missing components	The contract uses components this build does not have. Deploy the code first
Different contract	The build was made for another version of the contract
Unknown contract	Atlas has never seen the contract this build reports
No contract	No contract is active yet

A Production release cannot be approved while the website is out of sync. This stops editors from using a component that does not exist on the live site yet.

Adding a new component

1. Build and test the component in your website code.
2. Add it to the contract bundle with its fields, and to the page types where editors may insert it.
3. Validate and propose the contract. A site admin activates it.
4. Deploy the website. Studio shows In sync.
5. Editors can now use it.