Use AppPlaceholder to render server and client components

Content SDK's Next.js App Router template introduces the AppPlaceholder, a unified placeholder component that supports both server and client components. It provides a single, universal API and a consistent rendering pipeline that works regardless of the execution environment. This replaces the older placeholder approach by explicitly supplying the component map and the resolved Sitecore page, and by propagating these into every rendered component.

Import and use AppPlaceholder

You can use the AppPlaceholder by importing it in your layout and using it in place of your existing Placeholder.

To use the AppPlaceholder:

Use the following import statement:

RequestResponse

import { AppPlaceholder } from '@sitecore-content-sdk/nextjs';

Add it in your layout (for example, src/Layout.tsx):

RequestResponse

<main>
      <div id="content">
        {route && (
            <AppPlaceholder
              page={page}
              componentMap={componentMap}
              name="headless-main"
              rendering={route}
            />
        )}
      </div>
</main>

Required props

AppPlaceholder extends the traditional placeholder API with the following two required properties:

componentMap – a map of component names to implementations (server and/or client variants).
page – the fetched Sitecore page model (includes layout, route data, fields, and context).

These properties are now passed to all rendered components, so they can be used to render AppPlaceholder. Because each component now receives the page property, you generally no longer need the useSitecore() hook to access route-level context. You can directly use the page prop to access fields and rendering metadata.

Mark components for client execution

By default, components in App Router are Server Components. Mark a component as client-side only if it uses state/effects, browser APIs, or client-only context.

To mark a component for client execution:

Add 'use client'; at the top of your component file as shown:

RequestResponse

'use client';
import { Field, ImageField } from '@sitecore-content-sdk/nextjs';
// ... other imports

Mark the component as a client component in the component map.

React and Content SDK now treats the component as a client-side one, allowing you to use hooks inside the component. This also instructs AppPlaceholder to provide a component map to the component that matches the environment.

Use client error components

When passing custom error components to the AppPlaceholder, React Server Component constraints require them to be Client Components. You can implement a custom client error component in a dedicated file as shown:

Create a new file for the error component, for example, errors.tsx and mark it with 'use client'; as shown:

RequestResponse

'use client';
import React from 'react';

export const customError = () => {
  return (
    <div style={{ border: '2px solid red', padding: '10px', margin: '10px 0' }}>
      <h2 style={{ color: 'red' }}>Custom Error Component</h2>
      <p>Sorry, something went wrong while loading this component.</p>
    </div>
  );
};

Import it in the file where AppPlaceholder is used and pass it as an errorComponent:

RequestResponse

import { customError } from './errors';
...
<AppPlaceholder
  page={page}
  componentMap={componentMap}
  name="headless-main"
  rendering={route}
  errorComponent={customError}
/>

Do you have some feedback for us?

If you have suggestions for improving this article,