App Router + Design Studio in Content SDK 1.5: Making Sense of the Generated Maps

Content SDK 1.5.0 landed this week (February 24th) with a short release note and a big impact if you’re on the App Router: Design Studio can now securely generate component variants for Server Components.

That closes one of the last gaps between the Pages Router and App Router experience. It also made me realize that most people on my team had never really looked at the .sitecore folder that powers all this. So let’s do that.

The four files

Scaffold an App Router app with npx create-content-sdk-app and you’ll see this:

.sitecore/
  component-map.ts          # server component map
  component-map.client.ts   # client-safe component map
  import-map.server.ts      # what generated code can import on the server
  import-map.client.ts      # ...and on the client

On the Pages Router there’s one component map and one import map. On the App Router everything is split in two, because a component is either a Server Component or a Client Component, and Next.js won’t let you mix those freely.

Component maps: connecting Sitecore renderings to React

The component map is how a rendering name in Sitecore gets resolved to a React component. On the App Router you get two:

// .sitecore/component-map.ts (server)
import { BYOCWrapper, NextjsContentSdkComponent, FEaaSWrapper, Form } from '@sitecore-content-sdk/nextjs';

export const componentMap = new Map<string, NextjsContentSdkComponent>([
  ['BYOCWrapper', BYOCWrapper],
  ['FEaaSWrapper', FEaaSWrapper],
  ['Form', { ...Form, componentType: 'client' }],
]);

// .sitecore/component-map.client.ts (client)
import { BYOCClientWrapper, NextjsContentSdkComponent, FEaaSClientWrapper, Form } from '@sitecore-content-sdk/nextjs';

export const componentMap = new Map<string, NextjsContentSdkComponent>([
  ['BYOCWrapper', BYOCClientWrapper],
  ['FEaaSWrapper', FEaaSClientWrapper],
  ['Form', Form],
]);

Notice the componentType: 'client' on Form in the server map. That’s how the server side knows a component has to be handed off to the client side instead of being rendered as a Server Component.

You don’t maintain your own components in these files by hand. The sitecore-tools project component generate-map step (it’s wired into npm run dev and npm run build) scans the paths you list in sitecore.cli.config.ts:

// sitecore.cli.config.ts
export default defineCliConfig({
  config: scConfig,
  build: {
    commands: [
      generateMetadata(),
      generateSites(),
      extractFiles(),
      writeImportMap({ paths: ['src/components'] }),
    ],
  },
  componentMap: {
    paths: ['src/components'],
    exclude: ['src/components/content-sdk/*'],
  },
});

If a component isn’t showing up in Page builder, check two things first: is the file under one of those paths, and does the filename match the rendering’s component name in Sitecore?

Import maps: the allow-list for generated code

This is the part that matters for Design Studio.

When Design Studio generates a variant of a component, it’s producing new component code. That code has to import things – Text, RichText, Link, your own shared components – and it can’t just import anything from anywhere at runtime. The import map is the list of modules and exports that generated code is allowed to use.

writeImportMap({ paths: ['src/components'] }) builds those files for you, and on the App Router it builds a server one and a client one. Here’s a trimmed look at the server version:

// .sitecore/import-map.server.ts (auto-generated - don't edit by hand)
import { combineImportEntries, defaultImportEntries } from '@sitecore-content-sdk/nextjs/codegen';
import { Link, Text, RichText, NextImage } from '@sitecore-content-sdk/nextjs';

const importMapServer = [
  {
    module: '@sitecore-content-sdk/nextjs',
    exports: [
      { name: 'Link', value: Link },
      { name: 'Text', value: Text },
      { name: 'RichText', value: RichText },
      { name: 'NextImage', value: NextImage },
      // ...
    ],
  },
  // ...your own modules from src/components
];

What 1.5 adds is the secure preview mechanism that lets those generated variants render correctly as Server Components. Before this, App Router projects could run into trouble rendering AI-generated variants in Design Studio.

Practical tips

A few things I’ve learned getting App Router projects working smoothly with Design Studio:

• Keep shared UI in src/components. If generated variants should be able to use your Button or Card, they need to be in a path the import map generator scans.
• Be deliberate about 'use client'. Only mark components as client when they actually need state, effects or browser APIs. Every client component is a boundary the maps have to account for.
• Never hand-edit the generated files. They’re rebuilt on every dev start and build. If something’s missing, fix the source or the CLI config.
• Commit the .sitecore folder. Your build regenerates it, but having it in the diff makes it really obvious when a refactor accidentally drops a component from the map.
• If you’re on the App Router beta templates from late 2025, read the upgrade guides. 1.3 refactored the Design Library pieces for Server Components, and that was a breaking change for App Router apps.

Resources

• Content SDK 1.5.0 changelog: https://developers.sitecore.com/changelog/sitecoreai/25022026/content-sdk-1.5.0-adds-support-for-design-studio-in-app-router%E2%80%93based-applications
• Content SDK on GitHub (see CHANGELOG.md for 1.3 through 1.5): https://github.com/Sitecore/content-sdk