1. Getting started with Next.js App Router using Content SDK

Using the page prop vs the useSitecore() hook

Version:

When using Next.js App Router with the Content SDK, Sitecore context data is available through the page prop passed into components, rather than via the useSitecore() hook. This enables you to keep more components as Server Components and avoid unnecessary 'use client' usage.

Note

The useSitecore() hook and the page prop provide the same underlying data. However, useSitecore() is limited to client components, while the page prop is used in server components.

This topic explains the difference between the page prop and the useSitecore() hook, when to use each, and the benefits of preferring the page prop in App Router–based apps.

How App Router passes Sitecore context

In App Router apps, you render Sitecore content using the AppPlaceholder. It requires both a page and a componentMap and passes these into all rendered components:

import { AppPlaceholder } from '@sitecore-content-sdk/nextjs'; 
import componentMap from '.sitecore/component-map'; 
 
<main> 
  <div id="content"> 
    {route && ( 
      <AppPlaceholder 
        page={page} 
        componentMap={componentMap} 
        name="headless-main" 
        rendering={route} 
      /> 
    )} 
  </div> 
</main>

AppPlaceholder extends the traditional placeholder API with the page and componentMap props and propagates them into every rendered component. Because each component now receives the page property, you generally no longer need the useSitecore() hook to access route‑level context.

The page prop

The page prop is a strongly typed Page model returned by the SitecoreClient, containing layout, route, fields, and context. It's passed into layouts and renderings and then into AppPlaceholder, which forwards it to all components.

It works in server components by default and in client components when you explicitly mark them with 'use client'. Because the page prop is available in both server and client components, it is the recommended way to access Sitecore context in App Router apps.

You would typically use the page prop in the following cases:

  • Reading route fields (for example, page.layout.sitecore.route.fields).

  • Accessing site name, language, and other context stored on the Page model.

  • Passing Sitecore data further down as props.

The useSitecore() hook

The useSitecore() hook is a React hook provided by @sitecore-content-sdk/nextjs that exposes Sitecore context from SitecoreProvider. In current versions it returns { page, updatePage }. It works only in client components. Because useSitecore() is a React hook, using it forces the component to be a client component (directly or via a client provider). Contexts such as Sitecore Context, applied via SitecoreProvider and other React providers, are unavailable in Server Components.

You would typically use the useSitecore() hook in the following cases:

  • Reading page from context in a client component that is already interactive.

  • Calling updatePage to update the page context in response to client‑side events.

When to use page vs useSitecore()

You can use the page prop when you want the component to remain a Server Component, be rendered via AppPlaceHolder, and only need to read Sitecore data (fields, route info, site name, etc.)

This aligns with App Router’s server‑first model and the recommendation to pass required data as props into server components instead of relying on React context.

You can use the useSitecore() hook when the component is already a client component (for example, it uses useState, useEffect, browser APIs, or event handlers) or you need to update the page context (updatePage) in response to client‑side interactions.

Important

Do not add 'use client' to a component solely to call useSitecore() if you can instead receive the page prop.

Using the page prop over the useSitecore() hook provides several benefits:

  • App Router introduces a clear separation between server and client components and allows better performance, SEO, bundle size control, and security when you keep components on the server.

  • Avoiding unnecessary 'use client' reduces the amount of JavaScript sent to the browser and keeps more logic on the server.

  • AppPlaceholder is designed to work with both server and client components by explicitly supplying page and componentMap and propagating them into every rendered component.

  • Passing page as a prop is the recommended pattern for App Router, as contexts like SitecoreProvider are not available in server components.

If you have suggestions for improving this article, let us know!