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

Validate and maintain an atoms catalog

The atoms lock file records the accepted snapshot of your component catalog. Validation compares that snapshot with the current catalog so you can detect changes before continuing development or a build.

The CLI reads the catalog export from src/atoms/index.ts or src/atoms/index.tsx. For initial catalog and provider setup, see Get started with atoms.

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.

Generate the initial lock file

Scaffolding doesn't create .sitecore/atoms.lock.json. Generate it once, even if you keep the starter catalog empty:

npm run sitecore-tools:atoms:update

This script runs sitecore-tools project atoms update, which rewrites the lock file from the current catalog. Commit .sitecore/atoms.lock.json.

The starter's .gitignore ignores other files in .sitecore but keeps the atoms lock file:

.sitecore/*
!.sitecore/atoms.lock.json

If you are adding atoms to an existing app with this ignore rule, put the exception after it. Generate the lock file with the CLI; don't edit it manually or change its hashes.

Validate the catalog

To compare the current catalog with the lock file, run:

npm run sitecore-tools:atoms:validate

This script runs sitecore-tools project atoms validate. Validation detects differences; it doesn't accept them or rewrite the lock file.

The Pages Router, App Router, and App Router with Cache Components starters run validation at the start of dev and build. The build runs these tasks in order:

  1. Validate the atoms catalog.
  2. Generate the component map.
  3. Run sitecore-tools project build.
  4. Run the Next.js build.

For an existing app, add the validate and update scripts described in Get started with atoms, and run validation before the rest of the build.

Stop on catalog mismatches

The starters include this block in sitecore.cli.config.ts:

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

With breakOnError: false, validation logs catalog mismatches and lets dev and build continue. Set atoms.validation.breakOnError to true when mismatches should stop the process, for example in CI.

Accept intentional changes

After intentionally changing a component definition:

  1. Run npm run sitecore-tools:atoms:update to accept the current catalog.
  2. Run npm run sitecore-tools:atoms:validate to compare it with the updated snapshot.
  3. Commit the updated lock file with the catalog changes.

Use update to accept a change and validate to detect one. For component definitions and their metadata, see Define an atoms catalog.

Regenerate application metadata

After changing the catalog, regenerate application metadata as well as updating the lock file when component definitions change.

In a starter app, run:

npm run sitecore-tools:build 

This runs the configured metadata-generation command and the other Sitecore build tasks. The starter's dev and build scripts also run these tasks. Check the catalog at this path in .sitecore/metadata.json:

capabilities.designLibrary.atoms.metadata.catalog 

Confirm that it contains the expected component and action definitions. Action-only catalog edits also require fresh metadata even though action definitions are outside the lock-file validation check. Updating .sitecore/atoms.lock.json accepts the component definitions for validation. It doesn't regenerate .sitecore/metadata.json. For metadata configuration, see Get started with atoms.

Versions and definition hashes

Catalog and component versions are optional. The lock file stores the catalog version at the root and a component version under that component's entry. It omits each version when the corresponding catalog or component doesn't declare one.

The following example illustrates the lock-file structure. The hash text is a placeholder, not a generated hash. Don't use this example to create or edit a lock file manually:

{
  "version": "1.0.0",
  "generated": "2026-10-22T08:00:00.000Z",
  "atoms": {
    "Button": {
      "version": "1.0.0",
      "hash": "<sha256 of the component definition, excluding version>"
    }
  }
}

The hash covers the component definition except version. Validation reports a version mismatch separately from a definition-hash mismatch. It checks each version when either the current definition or the lock file sets that version.

When you set or change a catalog or component version, update the lock file in the same change. A version change doesn't replace the hash check.

Action changes

The lock file records component definitions. Action definitions are outside this check, so an action-only edit doesn't fail atoms validation. See Add actions and state bindings to atoms.

Retire or remove a component

To keep a component available for existing layouts while allowing Design Studio to leave it out of new generations, set legacy: true on its catalog entry, then run npm run sitecore-tools:atoms:update. Keep its catalog entry and registered renderer so existing usages can still render.

The legacy flag defaults to false and is sent to Design Studio. Actions also support legacy: true: existing usages still run, and Design Studio can leave the action out of new generations. Action definitions remain outside the lock-file check.

To remove a component, delete it from both the catalog and registry, then run npm run sitecore-tools:atoms:update. A component without a registered renderer doesn't render. See Implement atom renderers and slots.

For validation error codes and corrective steps, see Troubleshoot atoms.

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