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.
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:
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:
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:
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:
- Validate the atoms catalog.
- Generate the component map.
- Run
sitecore-tools project build. - 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:
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:
- Run
npm run sitecore-tools:atoms:updateto accept the current catalog. - Run
npm run sitecore-tools:atoms:validateto compare it with the updated snapshot. - 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:
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:
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:
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.