2.x
  1. Atoms in Content SDK apps (Early Access)

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.

Important

The features described in this topic are available only to customers enrolled in Early Access and are intended for testing in non-production environments.

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.

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. See Deploy a project and environment.

  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:

    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:

    {
        "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:

    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.

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.

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.

Connect the provider

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

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

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

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:

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:

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:

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:

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:

"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.

Generate and validate the lock file

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

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:

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:
npm run dev
  1. The starter runs its Sitecore build tasks, including metadata generation, before starting the development server. Open .sitecore/metadata.json and locate:
capabilities.designLibrary.atoms.metadata.catalog
  1. Confirm that the components list contains an entry named Heading and that its propsSchema includes the heading field.

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

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.

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.

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.

Next steps

For additional atom examples and installation instructions, see Content Kit components.

If you have suggestions for improving this article, let us know!