1. Sitecore Content SDK

What's new in Content SDK 2.1

Version:

Content SDK 2.1 introduces improvements across Next.js integrations, lightweight events tracking, search, and preview security, along with important bug fixes and maintenance updates.

To update your existing Content SDK 2.0 application to 2.1:

  1. In your existing application's package.json file, update every @sitecore-content-sdk package to version 2.1.0.

  2. Install the dependencies with the following command:

    npm install

Notable improvements and bug fixes

The following features, improvements, and bug fixes have been introduced in Content SDK 2.1. This is not an exhaustive list. Please review the Content SDK 2.1 changelog for a complete list of all changes.

Lightweight tracking and bot detection

See Lightweight tracking and bot detection for more information.

Upgrade to Next.js 16.2.0

Next.js has been upgraded from 16.1.1 to 16.2.0. See the Next.js 16.2 announcement for more information.

Authorize internal editing host preview requests using the PreviewProxy

When using Sitecore Pages to preview a site, users could open a page and preview it using the direct preview link even without the permission to access it. To overcome this, a new PreviewProxy is introduced that authorizes preview requests from internal editing hosts.

Note

Currently, this is only applicable to internal editing hosts deployed on SitecoreAI.

To use this:

In proxy.ts, import PreviewProxy and add it as the first proxy in defineProxy(...):

import { NextFetchEvent, type NextRequest } from 'next/server';
import {
  defineProxy,
  // ...other proxies
  PreviewProxy,
} from '@sitecore-content-sdk/nextjs/proxy';
import scConfig from 'sitecore.config';
import client from 'src/lib/sitecore-client';

export default function proxy(req: NextRequest, event: NextFetchEvent) {
  const preview = new PreviewProxy({
    client,
    ...scConfig.api.edge,
  });

  // ...other proxies (botTracking, locale, multisite, ...etc)

  return defineProxy(preview, /* ...other proxies */).exec(req);
}
Note

The PreviewProxy is purely additive. If you do not add it, behavior is unchanged. We recommend adding it if you serve preview requests from an internal editing host.

Access preview data via request headers

Content SDK apps using Next.js App Router deployed to Vercel displayed a 500 error page in preview when Draft Mode was enabled on statically generated routes. This occurred because the searchParams parameter was empty, leaving the route without preview data and causing the editing and preview flow to fail.

This is expected behaviour in Next.js. In Draft Mode, searchParams are intentionally not forwarded. The Next.js team has confirmed that searchParams should not be relied on within draftMode(), as preview data is designed to be passed through request headers instead.

The Content SDK now propagates editing preview data from the editing render route handler to the page through a dedicated request header and exposes a new helper to access it.

To use this:

  1. In your catch‑all page, find instances of searchParams usage:

    import { draftMode } from 'next/headers';
import client from 'src/lib/sitecore-client';

export default async function Page({ params, searchParams }: PageProps) {
  // ...
  const draft = await draftMode();
  if (draft.isEnabled) {
    const editingParams = await searchParams;
    if (isDesignLibraryPreviewData(editingParams)) {
      page = await client.getDesignLibraryData(editingParams);
    } else {
      page = await client.getPreview(editingParams);
    }
  }
  // ...
}

  2. Replace them with the new client.getPreviewData(...) helper to read preview data from headers(). as shown:

    import { draftMode, headers as nextHeaders } from 'next/headers';
import client from 'src/lib/sitecore-client';

export default async function Page({ params, searchParams }: PageProps) {
  // ...
  const draft = await draftMode();
  if (draft.isEnabled) {
    const headers = await nextHeaders();
    const previewData = client.getPreviewData(headers);

    if (isDesignLibraryPreviewData(previewData)) {
      page = await client.getDesignLibraryData(previewData);
    } else {
      page = await client.getPreview(previewData);
    }
  }
  // ...
}
    Important

    For existing apps, preview data continues to be appended to searchParams. This does not cause the app to break on environments where searchParams still flows through. This duplication will be removed in the next major release. We recommend migrating to the client.getPreviewData(...) method ahead of that.

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