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.
The features described in this topic are available only to customers enrolled in Early Access and are intended for testing in non-production environments.
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:
-
In the Deploy app, create and deploy a project based on the XM Cloud starter repository. See Deploy a project and environment.
-
Identify the site you want to use for atoms development. Create a site if your environment doesn't already contain one.
-
Clone the repository connected to your deployed project:
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:
-
In the cloned repository, open
xmcloud.build.jsonand identify the rendering application you intend to replace. ItsrenderingHostsentry contains the application path.For example, the following excerpt identifies an application under
examples/kit-nextjs-skate-park:Use the path configured in your project and keep the remaining host configuration.
-
In a separate local folder, run:
-
Follow the initializer prompts to create your Next.js application.
-
Replace the contents of the identified rendering application folder with the generated application, including its configuration files and dotfiles.
-
Keep the repository-level files and folders, including
authoringandxmcloud.build.json. -
Ensure the application sits directly at the configured rendering-host path. If you choose a different location, update the corresponding
renderingHostsentry.
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.
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.
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:
They pass both to SitecoreProvider through atomsConfig. The minimum atoms configuration is:
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:
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:
Inside the existing build.commands array, the metadata command includes:
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:
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:
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:
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:
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
- Start the application:
- The starter runs its Sitecore build tasks, including metadata generation, before starting the development server. Open
.sitecore/metadata.jsonand locate:
-
Confirm that the
componentslist contains an entry namedHeadingand that itspropsSchemaincludes theheadingfield. -
To regenerate metadata separately after catalog changes, run:
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.
- Define an atoms catalog to add field props, editor hints, and placement constraints.
- Implement atom renderers and slots to support nested content.
- Add actions and state bindings to implement interactions.
- Configure styling for atom-based components to enable generated class styles and optional site-level theming.
- Create atoms using AI with the starter's agent guidance.