Configure styling for atom-based components
Class names in component layouts can be absent from your app's source files, so the production CSS build doesn't include them. Runtime CSS compilation lets the SDK style these class names when it renders a layout and during Design Studio editing.
This topic assumes you have connected a catalog and registry to SitecoreProvider. 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.
Set the catalog styling solution
In src/atoms/index.tsx, set stylingSolution: 'tailwind' on the existing catalog when your app styles atoms with Tailwind. For example, an empty catalog with this setting is:
stylingSolution tells Design Studio whether to generate Tailwind classes or inline CSS. Its values are tailwind and inline-css; the default is inline-css. The SDK sends this setting with the catalog. It doesn't register a runtime CSS compiler.
For other catalog settings, see Define an atoms catalog.
Enable site-level theming
Site-level theming loads a design-token stylesheet for the current SitecoreAI site. Enable it through theming.mode in sitecore.config.ts. This configuration is separate from the catalog's stylingSolution and runtime atom CSS compilation:
| Setting | Purpose |
|---|---|
Catalog stylingSolution | Tells Design Studio whether the app uses Tailwind classes or inline CSS. |
| registerTailwindCssCompiler and compileCssAction | Compile class names used in atom-based component layouts. |
| Site configuration theming.mode | Controls whether the SDK includes the site-level design-token stylesheet. |
Configure theming mode
In the existing sitecore.config.ts, add theming to the defineConfig configuration:
Keep the other settings already configured in your app.
The Next.js configuration reads the client context ID from NEXT_PUBLIC_SITECORE_EDGE_CONTEXT_ID, unless you explicitly configure api.edge.clientContextId.
Include the theme stylesheet
The SDK's SitecoreClient.getHeadLinks method includes the site-level theme stylesheet when:
theming.modeissite.- The layout response contains
sitecore.context.site.name. - A client Edge context ID is configured.
The starters created using the CLI render these links through their SitecoreStyles component and construct the SDK client with the application configuration. In an existing app, ensure your SDK client receives the theming configuration and your page renders the links returned by getHeadLinks.
The site-level theme stylesheet uses this URL structure:
Site-level theming is independent of the enableThemes option used for Design Studio stylesheets. Setting enableThemes to false doesn't disable site-level theming. Use theming.mode: 'none' to disable it.
Apply the theme class to the page
The starters conditionally add sc-ds-theme to <body> when site-level theming is enabled.
For an existing app, import the configuration and helpers in the file that renders <body>:
Use this expression for the theme class:
Apply the change in:
src/app/layout.tsxfor App Router and App Router with Cache Components.src/pages/_document.tsxfor Pages Router.- If
<body>already has classes, combine the theme class with those classes.
Expose the theming configuration to the editor
Pass the same theming configuration to the editing configuration endpoint so SitecoreAI can determine the application's theming configuration.
For App Router and Cache Components, add theming to the existing options in src/app/api/editing/config/route.ts:
For Pages Router, add it to the existing middleware options in src/pages/api/editing/config.ts:
Import scConfig from sitecore.config if the file doesn't already import it. Keep the endpoint's existing imports, options, and exports.
Verify the integration
After restarting the app:
- Open a page for the configured SitecoreAI site.
- Inspect
<body>and confirm that its classes includesc-ds-theme. - Inspect the rendered stylesheet links and confirm that one uses the site-theme delivery URL.
- In the browser's network tools, check that the theme stylesheet request succeeds.
- Check the editing configuration response and confirm that its theming object has
mode: 'site'.
If the stylesheet link is missing, check the theming mode, site name in the layout response, and client Edge context ID.
This procedure configures the SDK to load a site theme. It doesn't create or assign tokens or Token Sets in SitecoreAI.
Preview theme changes
The SDK can apply theme CSS updates while a page is in editing or preview mode. This lets the preview reflect theme changes without replacing the site's delivered stylesheet link. The starters pass the theming configuration to SitecoreProvider. For an existing app, import scConfig from sitecore.config if necessary and add this prop to the existing provider:
Keep the provider's other props, including atomsConfig. Retain the app's EditingScripts integration. The SDK's EditingScripts component includes ThemePreviewEvents, which listens for theme-update messages in editing and preview modes. Apps using this integration don't need a second theme-update listener.
When a valid update arrives, the SDK applies the CSS in a preview <style> element. A later update replaces that element; an empty CSS update removes it. These updates change the preview and don't save or publish the theme.
Set theming.mode to site to use the configured site theme and its preview integration. The listener is inactive when the configured mode is none, and the SDK doesn't include it on normal pages through EditingScripts.
This behavior is separate from compileCssAction, which compiles classes in atom-based layouts. For preview issues, see Troubleshoot atoms.
Check the starter configuration
The starters include different CSS compilation configuration:
| Starter | Configuration |
|---|---|
| App Router | Registers the Tailwind compiler at startup and passes compileCssForDocumentAction to the provider. |
| App Router with Cache Components | Registers the Tailwind compiler at startup and passes compileCssForDocumentAction to the provider. |
| Pages Router | Includes the catalog, registry, provider, and CLI commands, but doesn't register a CSS compiler. Atoms still render without one. |
The following Tailwind setup describes the App Router and Cache Components integration.
Register the Tailwind compiler at startup
Published pages use the compiler registered when the server starts. The SDK collects class tokens from each layout element's className prop and passes them to that compiler.
The App Router and Cache Components starters use these startup files:
Pass the path to your app's Tailwind stylesheet. A relative path resolves from the app root. With no argument, registerTailwindCssCompiler uses src/app/globals.css.
Keep @tailwindcss/node in serverExternalPackages in the Next.js configuration because it ships native binaries:
Compile CSS during Design Studio editing
Design Studio editing uses compileCssAction to call the same registered compiler. In the App Router and Cache Components starters, src/Providers.tsx imports the Server Action:
Pass it as compileCssAction on the existing provider's atomsConfig:
compileCssForDocumentAction returns an empty string when no compiler is registered or the document has no class names. Setting stylingSolution: 'tailwind' alone doesn't enable this compilation.
If a document contains class names but no compiler is registered, the component still renders without compiled CSS for those classes. For related issues, see Troubleshoot atoms.
Use a custom CSS compiler
To use a compiler other than Tailwind, register it once from Node.js startup code with setAtomsCssCompiler:
This snippet is illustrative: compileClasses is a placeholder for your own compiler implementation, not a Content SDK API. The registered function must accept string[] class tokens and return Promise<string> containing the compiled CSS.
The registration is shared by instrumentation, React Server Components, and Server Actions. Published rendering and the editing action use the same registered compiler.