Register a component in the component map

A component map contains a list of all the components in your Content SDK app. Each component is mapped to a corresponding component within Sitecore AI, allowing marketers to use it in Pages. You can view the component map at .sitecore/component-map.ts. By default, Content SDK generates a component map when you execute the build and dev scripts.

The following code snippets shows the structure of a component map in a Content SDK app that contains imports for the built-in components, components from the app itself, and other non-dynamic components. The component name is written first, followed by the imported component itself:

RequestResponse

// Below are built-in components that are available in the app, it's recommended to keep them as is
import { BYOCWrapper, NextjsJssComponent, FEaaSWrapper } from '@sitecore-content-sdk/nextjs';
import { Form } from '@sitecore-content-sdk/nextjs';
// end of built-in components

// Components imported from the app itself
import * as CdpPageView from 'src/components/CdpPageView';
....
import * as Title from 'src/components/Title';

// Components must be registered within the map to match the string key with component name in Sitecore
export const componentMap = new Map<string, NextjsJssComponent>([
  ['BYOCWrapper', BYOCWrapper],
  ['FEaaSWrapper', FEaaSWrapper],
  ['Form', Form],
  ['CdpPageView', CdpPageView],
  [....],
  ['Title', Title],
]);

export default componentMap;

Tip

Automatic component map generation trades flexibility for simplicity. Advanced use-cases involving Next.js dynamic() imports require a self-managed component map. To disable automatic component map generation, remove the following from the build and dev scripts:

RequestResponse

sitecore-tools:generate-map

Component map configuration

The configuration for automatic component map generation lives inside the sitecore.cli.config.ts file. Out-of-the-box, the configuration is as shown:

RequestResponse

componentMap: {
    paths: ['src/components'],
},

This configuration generates the component map using all the components that live inside src/components. In addition to the paths parameter, the componentMap object also allows the following parameters:

exclude
destination
componentImports
mapTemplate

See the table below for detailed descriptions of these parameters and their types:

Parameter	Type	Description
`paths`	`string[]`	Provide a list of paths (glob or otherwise) for the component map to pull and register components from. One component is imported per component file to support SXA variants. For example, in the default starter kit app, a component is imported as shown: RequestResponse `import * as CdpPageView from 'src/components/CdpPageView';`
`exclude`	`string[]`	Provide a list of rules (provided as glob paths) to exclude components from being registered. The logic considers all components under `paths` and then removes the ones matching from `exclude`.
`destination`	`string`	Provide a custom destination folder for the generated `component-map.ts` file. The default destination is the `.sitecore` folder. Warning If you modify this property, ensure that the component-map imports reference the new location.
`componentImports`	`ComponentImport[]`	Fine tune your component imports within the component map or add components from module dependencies. For example, to import some components from a package and create a named import, use the below `ComponentImport` definition: RequestResponse `{ importName: 'MyPackageImport', importInfo: { importFrom: '@my/package/import', namedComponents: ['NamedA', 'NamedB'], }, },` This imports `NamedA` and `NamedB` into the component map as shown: RequestResponse `import { NamedA, NamedB } from '@my/package/import';` You can also use individual `ComponentImport` entries to import components as SXA components from your local app: RequestResponse `{ importName: 'LocalSXAComponent', importInfo: { importFrom: 'src/components/LocalSxaComponent', }, },` This imports `LocalSXAComponent` into the component map as shown: RequestResponse `import * as LocalSXAComponent from 'src/components/LocalSxaComponent';`
`mapTemplate`	`(components: ComponentFile[], componentImports?: ComponentImport[]) => string`	Provide an override for the function that forms the component-map template. It accepts component definitions for component files parsed from the `paths` parameter and component import definitions from the `componentImports` parameter. It should return a string with the contents of `component-map.ts`.

Registering a component manually

You can manually manage component maps when working with advanced use-cases like Next.js's dynamic() imports. Before doing so, make sure your SitecoreAI environment has the component you intend to map your component to. Also, ensure you've turned off automatic component map generation by removing the following from the build and dev scripts:

RequestResponse

sitecore-tools:generate-map

To register a component:

Import the component and its variants to the component map. Depending on whether you want to use a standard component, or a dynamic component with or without variants, this import works differently:
- For a standard (non-dynamic) component, write an import statement similar to the following example:
  RequestResponse
  import * as MyComponent from 'src/components/MyComponent';
- For a dynamic component, write an import statement similar to the following example:
  RequestResponse
  const MyDynamicComponent = dynamic(() => import('src/components/MyDynamicComponent'));
  Note
  If you're using a dynamic component, you can also do the following if needed:
  
  Configure a dynamic import to use component-level props
  
  Configure a dynamic import to use one or more variants
When you've finished configuring your component import, add a line to componentMap containing the name of the SitecoreAI rendering item followed by the imported component name. The following example maps MyDynamicComponent to a rendering with the same name:
RequestResponse
```
['MyDynamicComponent', MyDynamicComponent],
```

Configure a dynamic import to use component-level props

If you're importing a dynamic component and you want to use component-level props, add a dynamic module to the import and name the component Default as shown in the following example:

RequestResponse

const MyDynamicComponent = {
  dynamicModule: () => import('src/components/MyDynamicComponent'),
  Default: dynamic(() => import('src/components/MyDynamicComponent')),
};

Configure a dynamic import to use one or more variants

If you're importing a dynamic component and you want to include standard or dynamic variants, add them to the dynamic import and—if you haven't already done so—name the original component the Default variant. You can also use variants with non-dynamic components.

In the following example, the Default component has a standard variant named Variant1 and a dynamic variant named Variant2:

RequestResponse

import Variant1 from 'src/components/Variant1';
...
const MyDynamicComponent = {
  ...
  Default: dynamic(() => import('src/components/MyDynamicComponent')),
  Variant1: Variant1,
  Variant2: dynamic(() => import('src/components/MyDynamicComponentVariant2')),
};

Do you have some feedback for us?

If you have suggestions for improving this article,