1. Developer guides

Register a component in the component map

Version: 1.x

A component map contains a list of all the components in your Content SDK app. Each component is mapped to a corresponding component within SitecoreAI, 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 components. The component name is written first, followed by the imported component itself:

// Below are built-in components that are available in the app, it's recommended to keep them as is
import { AngularContentSdkComponent } from '@sitecore-content-sdk/angular';

import { ScFormComponent } from '@sitecore-content-sdk/angular';
// end of built-in import section
import * as TitleComponent from 'src/app/components/title.component';
import * as CdpPageViewcomponent from 'src/app/components/content-sdk/cdp-page-view.component';

export const componentMap = new Map<string, AngularContentSdkComponent>([
  ['Form', ScFormComponent],
  ['Title', { ...TitleComponent }],
  ['CdpPageView', { ...CdpPageViewcomponent }],
]);

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:

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:

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:

Property

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:

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:

{
  importName: 'MyPackageImport',
  importInfo: {
    importFrom: '@my/package/import',
    namedComponents: ['NamedA', 'NamedB'],
  },
},

This imports NamedA and NamedB into the component map as shown:

import { NamedA, NamedB } from '@my/package/import';

You can also use individual ComponentImport entries to import components as SXA components from your local app:

{
  importName: 'LocalSXAComponent',
  importInfo: {
    importFrom: 'src/components/LocalSxaComponent',
  },
},

This imports LocalSXAComponent into the component map as shown:

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 also manually manage component maps. 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:

sitecore-tools:generate-map

To register a component, import the component and its variants to the component map.

import * as MyComponent from 'src/components/MyComponent';

Configure using one or more variants

If you're importing a component and you want to include variants, name the original component the Default variant and add variant names for variant imports.

In the following example, the Default component has a standard variant named Variant1.

import Variant1 from 'src/components/variant.component';
import TitleComponent from 'src/app/components/title.component';
...
const MyVariantComponent = {
  ...
  Default: TitleComponent,
  Variant1: Variant1,
};
If you have suggestions for improving this article, let us know!