---
title: "Manage component maps for client and server components"
slug: "manage-component-maps-for-client-and-server-components"
abstract: "Learn how the Sitecore Content SDK generates dual component maps in the Next.js App Router to separate server and client components, prevent server code in browser bundles, and optimize performance."
---
# Manage component maps for client and server components

The Content SDK Next.js App Router template generates two component map files to keep server and client concerns isolated. This avoids shipping server‑only logic to the browser, and enables lean client bundles. See the official [Next.js documentation](https://nextjs.org/docs/app/getting-started/server-and-client-components) to learn more about server and client components.

## Generated files

The Content SDK Next.js App Router template generates both maps by default:

- `component-map.ts` – Includes all components (server and client) and is used in server-side code.
- `component-map.client.ts` – Includes only client components and is used in client-side code.

Pages Router projects generate a single `component-map.ts` unless you force dual maps.

## Import patterns

You must import component maps differently depending on whether you're in a server or client component.

### Import component map in server components

Use the full map in server components (the default environment in App Router) as shown:

```ts
import { AppPlaceholder, Page } from '@sitecore-content-sdk/nextjs';
import componentMap from '.sitecore/component-map';

export default function Layout({ page }: { page: Page }) {
  return (
    <AppPlaceholder
      page={page}
      componentMap={componentMap}
      name="headless-main"
      rendering={page.layout.sitecore.route}
    />
  );
}
```

When using the `AppPlaceholder` in a server component, you must use the `component-map.ts` file.

### Import component map in client components

Use the client-safe component map in client components. The following snippet defines a client-side `Providers` component that's a global state provider.

```ts
'use client';
import components from '.sitecore/component-map.client';
import scConfig from 'sitecore.config';

export default function Providers({ children, page }) {
  return (
    <SitecoreProvider api={scConfig.api} componentMap={components} page={page}>
      {children}
    </SitecoreProvider>
  );
}
```

Then, use a client-side wrapper component to expose a Sitecore placeholder named `container`, to allow content authors to dynamically place components inside it via Sitecore. Because it's a client component, you need to use the client component map and the `useSitecore()` hook to obtain the page context.

```ts
'use client';

import { AppPlaceholder, ComponentRendering, useSitecore } from '@sitecore-content-sdk/nextjs';
import componentMap from '.sitecore/component-map.client';

type Props = {
  rendering: ComponentRendering;
};

export const Container = ({ rendering }: Props) => {
  const { page } = useSitecore();

  return (
    <div>
      <h1>Container</h1>
      <AppPlaceholder
        name="container"
        rendering={rendering}
        componentMap={componentMap}
        page={page}
      />
    </div>
  );
};
```

> [!important]
> When using the `AppPlaceholder` in a client component, you must use the `component-map.client.ts` file.
>
> By design, server components cannot be used within a client component. However, you can render server components in a server component and then pass its result down to a client component as a prop.

## Component classification

Content SDK classifies components during build. Based on specific conditions, it classifies them into three as shown:

- Client – File begins with `'use client'`.

    ```ts
    'use client';

    export default function InteractiveButton() {
      const [count, setCount] = React.useState(0);
      return <button onClick={() => setCount(count + 1)}>{count}</button>;
    }
    ```

- Server – Uses server‑only modules (for example, `next/headers`, `fs`, `path`).

    ```ts
    import { headers } from 'next/headers';

    export default async function ServerComponent() {
      const headersList = headers();
      return <div>User Agent: {headersList.get('user-agent')}</div>;
    }
    ```

- Universal – Uses only code safe in both environments. Universal components appear in both maps.

You can also explicitly define the component type using the `componentType` const as shown.

```ts
export const componentType = 'client';

export default function MyComponent() {
  return <div>Explicitly marked as client</div>;
}
```

Valid values for `componentType` are:

- `'server'`
- `'client'`
- `'universal'`

## Component map generation

You can generate component maps with the following CLI command:

```shell
sitecore-tools:generate-map
```

The result is based on your configuration and can contain one or both of the following:

- `component-map.ts` - Contains server, client (client entries explicitly declare type), and universal components as shown:

    ```ts
    export const componentMap = new Map<string, NextjsContentSdkComponent>([
      ['ServerHero', ServerHero],
      ['ClientButton', { component: ClientButton, componentType: 'client' }],
      ['Card', Card],
    ]);
    ```

- `component-map.client.ts` - Contains only client and universal components as shown:

    ```ts
    export const componentMap = new Map<string, NextjsContentSdkComponent>([
      ['ClientButton', ClientButton],
      ['Card', Card],
    ]);
    ```

> [!note]
> Server‑only components never appear in the client map, preventing runtime errors and larger bundles.

## Configure component map generation behavior

Content SDK provides the following two flags that you can use to control how component maps are generated:

- `clientComponentMap`
- `includeVariants`

### clientComponentMap flag

Use this to control the component map generation behavior. If the flag isn't specified, Content SDK automatically detects your Next.js router type and generates component maps as shown:

- For App Router (projects with the `app` or `src/app` directory) - generates both `component-map.ts` and `component-map.client.ts` files.
- For Pages Router (projects with the `pages` or `src/pages` directory) - generates only the `component-map.ts` file.

You can also override the auto-detection in `sitecore.cli.config.ts` by setting the `clientComponentMap` as shown:

```ts
export default defineCliConfig({
  componentMap: {
    paths: ['src/components'],
    clientComponentMap: true,  // force dual maps with custom components
    // or
    clientComponentMap: false, // force single map
    ...
  },
});
```

### includeVariants flag

Content SDK can include component variants along with their base components during map generation. To control variant inclusion, you can use the `includeVariants` flag. It defaults to `true`. A variant is any component file whose name follows `BaseComponent.<variantName>.(ts|tsx|js|jsx)`. Variants also use the same naming convention as base components.

For example, consider `PromoBlock.tsx` to be a base component. A variant of this could be `PromoBlock.green-bg.tsx`.

By default, when `includeVariants` is `true`, the component map for this combination of base component and variant is generated as shown:

```ts
import PromoBlock from '@/components/PromoBlock';
import PromoBlockgreenbg from '@/components/PromoBlock.green-bg';

export const componentMap = new Map<string, NextjsContentSdkComponent>([
  // base + variant merged into the SAME key
  ['PromoBlock', { ...PromoBlockgreenbg, ...PromoBlock }],
]);
```

You can also override the default in `sitecore.cli.config.ts` by setting `includeVariants` to `false` as shown:

```ts
export default defineCliConfig({
  componentMap: {
    paths: ['src/components'],
    ...
    includeVariants: false,
  },
});
```

When set to `false`, base components are included while variants are omitted from all generated map(s). Client/server filtering still applies to the remaining base components.