---
title: "Get started with atoms"
slug: "get-started-with-atoms"
abstract: "Create an atoms-enabled Content SDK app, connect it to SitecoreAI, and define and verify your first atom."
---
# Get started with atoms

This topic explains how to create an atoms-enabled Content SDK application, connect it to SitecoreAI, and register a heading atom that Design Studio can use in component layouts.
For an overview of catalogs, registries, and component layouts, see [Atoms in Content SDK apps](https://doc.sitecore.com/sai/en/developers/content-sdk/20/atoms-in-content-sdk-apps.html).

> [!important]
> The features described in this topic are available only to customers enrolled in [Early Access](https://forms.cloud.microsoft/Pages/ResponsePage.aspx?id=hAFwkRTDyU27fqQR30VqHj_zY3lpy3dGhZKklnheMCxURUpHTkhSSzI4QkhCUFMzSDM2M1ZGRkYwMi4u) and are intended for testing in non-production environments.

> [!note]
> **Before you begin**
> You need:
> - Access to SitecoreAI and the Deploy app.
> - Access to the repository connected to your SitecoreAI project.
> - A local development environment that meets the generated application's prerequisites.

This procedure uses the beta starter created using the CLI with the `beta.atoms` initializer tag. If you already have an atoms-enabled application connected to SitecoreAI, skip to [Define the atom and its renderer](https://doc.sitecore.com/sai/en/developers/content-sdk/20/get-started-with-atoms.html#define-the-atom-and-its-renderer).

## Prepare the SitecoreAI project

Before you can start using atoms, you must prepare your SitecoreAI project:

1. In the Deploy app, create and deploy a project based on the [XM Cloud starter repository](https://github.com/Sitecore/xmcloud-starter-js). See [Deploy a project and environment](https://doc.sitecore.com/sai/en/developers/sitecoreai/getting-started-with-sitecoreai/deploy-a-project-and-environment.html).
2. Identify the site you want to use for atoms development. Create a site if your environment doesn't already contain one.
3. Clone the repository connected to your deployed project:
    
    ```bash
    git clone <your-project-repository-url>
    ```

    Use your project's repository URL, rather than cloning the upstream starter repository again.

## Create the atoms-enabled application

Once you've cloned the application repository, you can enable it for atoms usage:

1. In the cloned repository, open `xmcloud.build.json` and identify the rendering application you intend to replace. Its `renderingHosts` entry contains the application path.

    For example, the following excerpt identifies an application under `examples/kit-nextjs-skate-park`:

    ```json
    {
        "renderingHosts": {
            "nextjsstarter": {
            "path": "./examples/kit-nextjs-skate-park"
            }
        }
    }
    ```

    Use the path configured in your project and keep the remaining host configuration.

2. In a separate local folder, run:

    ```bash
    npx create-content-sdk-app@beta.atoms
    ```

3. Follow the initializer prompts to create your Next.js application.
4. Replace the contents of the identified rendering application folder with the generated application, including its configuration files and dotfiles.
5. Keep the repository-level files and folders, including `authoring` and `xmcloud.build.json`.
6. Ensure the application sits directly at the configured rendering-host path. If you choose a different location, update the corresponding `renderingHosts` entry.

The beta's Pages Router, App Router, and App Router with Cache Components starters include an empty atoms catalog and registry, provider integration, metadata configuration, and validation scripts.

The generated application has its own components and layout. Replacing a starter application doesn't carry over that starter's component implementations. Once you've created the atoms enabled starter using the CLI and replaced it in your existing application repository, you can [Connect your Content SDK app to SitecoreAI](https://doc.sitecore.com/sai/en/developers/content-sdk/20/connect-your-content-sdk-app-to-sitecoreai.html).

## Define the atom and its renderer

In `src/atoms/index.tsx`, add a `Heading` entry to the catalog and a matching renderer to the registry. If you have already defined atoms, add these entries to the existing maps.

```tsx
import { z } from 'zod';
import {
  defineAtomsCatalog,
  defineAtomsRegistry,
  textFieldSchema,
} from '@sitecore-content-sdk/nextjs/atoms';

export const catalog = defineAtomsCatalog({
  components: {
    Heading: {
      props: z.object({
        heading: textFieldSchema(),
      }),
      description: 'A second-level heading',
    },
  },
  actions: {},
});

export const registry = defineAtomsRegistry(catalog, {
  components: {
    Heading: ({ props }) => <h2>{props.heading?.value}</h2>,
  },
});
```

The catalog and registry keys must match. In this example, both use `Heading`.

`textFieldSchema()` defines a Sitecore text field with a `{ value: ... }` shape and attaches the editor hint for a Single-Line Text control. The renderer reads the field through `props.heading?.value`.

The catalog requires `actions`. Use an empty object when the catalog has no actions.

> [!important]
> Name the catalog export `catalog`. The CLI reads this export from `src/atoms/index.ts` or `src/atoms/index.tsx`. For more prop types and catalog settings, see [Define an atoms catalog](https://doc.sitecore.com/sai/en/developers/content-sdk/20/define-an-atoms-catalog.html).

## Connect the provider

The starters import the catalog and registry in `src/Providers.tsx`:

```tsx
import { catalog, registry } from 'src/atoms';
```

They pass both to `SitecoreProvider` through `atomsConfig`. The minimum atoms configuration is:

```ts
atomsConfig={{ catalog, registry }}
```

Check that your provider includes this configuration. Pass the whole return value of `defineAtomsRegistry` as `registry`, rather than only its nested `registry` property. The registry API is a Client Component module. In App Router apps, keep this integration in the client provider. The App Router and Cache Components starters also pass optional navigation and CSS compilation settings:

```ts
atomsConfig={{
  catalog,
  registry,
  navigate: router.push,
  compileCssAction: compileCssForDocumentAction,
}}
```

Keep these properties if they're already configured. The heading renderer in this example doesn't require either property. Register atoms through `atomsConfig`. Keep the component map for your Sitecore rendering components.

## Generate catalog metadata

The starters pass the catalog to `generateMetadata` in `sitecore.cli.config.ts`. Check that the file imports:

```ts
import { ATOMS_CATALOG_METADATA_KEY } from '@sitecore-content-sdk/nextjs/atoms';
import { catalog } from 'src/atoms';
```

Inside the existing `build.commands` array, the metadata command includes:

```ts
generateMetadata({
  appInputs: {
    [ATOMS_CATALOG_METADATA_KEY]: catalog,
  },
}),
```

Keep the existing `generateMetadata` import from `@sitecore-content-sdk/nextjs/tools`, the other `build` commands, and any additional metadata options or application inputs.
The command writes `.sitecore/metadata.json`. The generated `designLibrary.atoms` capability includes the catalog when the SDK detects the application's Design Studio integration and atoms provider configuration. Metadata generation describes the catalog for integration. It is separate from lock-file validation.

## Configure catalog validation

The starters include the following block in `sitecore.cli.config.ts`:

```ts
atoms: {
  validation: {
    breakOnError: false,
  },
},
```

With `breakOnError` set to `false`, validation logs catalog mismatches and lets `dev` and `build` continue. Set it to `true` when mismatches should stop the process, for example in CI. The starters also include these entries in the `scripts` object in `package.json`:

```json
"sitecore-tools:atoms:validate": "sitecore-tools project atoms validate",
"sitecore-tools:atoms:update": "sitecore-tools project atoms update"
```

The starter's `dev` and `build` scripts run validation before component-map generation and the remaining Sitecore build tasks. For detailed validation behavior, see [Validate and maintain an atoms catalog](https://doc.sitecore.com/sai/en/developers/content-sdk/20/validate-and-maintain-an-atoms-catalog.html).

## Generate and validate the lock file

Scaffolding doesn't create `.sitecore/atoms.lock.json`. Generate it after defining the atom:

```bash
npm run sitecore-tools:atoms:update
```

The command writes a snapshot of the component definitions. Commit the lock file with the catalog and registry. The starter's `.gitignore` keeps this file while ignoring other generated files in `.sitecore`.

Validate the catalog against the snapshot using:

```bash
npm run sitecore-tools:atoms:validate
```

After an intentional change to a component definition, update the lock file again. Leave the generated hashes unchanged. Generate a lock file even if you keep the starter's catalog empty.

## Verify the generated catalog


1. Start the application:

  ```bash
  npm run dev
  ```

2. The starter runs its Sitecore build tasks, including metadata generation, before starting the development server. Open `.sitecore/metadata.json` and locate:

  ```text
  capabilities.designLibrary.atoms.metadata.catalog
  ```

3. Confirm that the `components` list contains an entry named `Heading` and that its `propsSchema` includes the `heading` field.

4. To regenerate metadata separately after catalog changes, run:

  ```bash
  npm run sitecore-tools:build
  ```

A valid empty catalog contains empty `components` and `actions` lists. A catalog value of just `{}` indicates missing catalog input or a serialization failure. For missing or incomplete metadata, see [Troubleshoot atoms](https://doc.sitecore.com/sai/en/developers/content-sdk/20/troubleshoot-atoms.html#the-atoms-capability-or-catalog-metadata-is-missing).

Open the local URL reported by the development server, normally `http://localhost:3000`. Check that the application starts and can retrieve data for the selected site. If a page uses components from the original starter, you might need to carry over those implementations for the page to render completely.

## Preview the component layout

Connecting the app to SitecoreAI gives it access to site data. To use the local app inside Design Studio, also configure the local host connection. See [Connect your local host to Pages](https://doc.sitecore.com/sai/en/developers/sitecoreai/environment-editing-hosts-and-rendering-hosts/connect-your-local-host-to-pages.html).

During low-code preview, the app sends its catalog to Design Studio. When Design Studio supplies a component layout that uses `Heading`, the app renders that element with the registered renderer and updates it as the layout changes.

Registering `Heading` doesn't automatically display it on a local page. The component layout determines where to use it and which prop values to pass. Metadata verification confirms the generated catalog; it doesn't verify visual rendering.

On a page, a nonempty `ComponentRef` rendering parameter selects the atom-based layout rendering path. For more information, see [Atoms in Content SDK apps](https://doc.sitecore.com/sai/en/developers/content-sdk/20/atoms-in-content-sdk-apps.html#atoms-and-sitecore-renderings).

## Next steps

For additional atom examples and installation instructions, see [Content Kit components](https://content-kit.vercel.app).

- [Define an atoms catalog](https://doc.sitecore.com/sai/en/developers/content-sdk/20/define-an-atoms-catalog.html) to add field props, editor hints, and placement constraints.
- [Implement atom renderers and slots](https://doc.sitecore.com/sai/en/developers/content-sdk/20/implement-atom-renderers-and-slots.html) to support nested content.
- [Add actions and state bindings](https://doc.sitecore.com/sai/en/developers/content-sdk/20/add-actions-and-state-bindings-to-atoms.html) to implement interactions.
- [Configure styling for atom-based components](https://doc.sitecore.com/sai/en/developers/content-sdk/20/configure-styling-for-atom-based-components.html) to enable generated class styles and optional site-level theming.
- [Create atoms using AI](https://doc.sitecore.com/sai/en/developers/content-sdk/20/create-atoms-using-ai.html) with the starter's agent guidance.