Version 2.0.0 of the Sitecore Content SDK dropped yesterday. It's a big release, not just in terms of new features, but in terms of what those features shows about where the SDK is heading. There are new capabilities, a handful of meaningful breaking changes too :), and some architectural decisions that are worth thinking through before you hit upgrade.
In this post I'm trying to walk through everything that matters, with context on what each change actually means in practice.
If you've been following along, you'll know I covered v1.5 last month in Sitecore Content SDK 1.5: Why It's Time to Leave JSS Behind. That post covered the migration case and what 1.5 unlocked. 2.0 builds on that foundation, but it raises the upgrade bar with some non-trivial breaking changes, so let's be precise about what you're walking into.
New Features
Search: `@sitecore-content-sdk/search`
This is the headline addition. The SDK now ships a first-party `@sitecore-content-sdk/search` package, pulling search capability directly into the Content SDK ecosystem.
The package introduces a `SearchService` class for querying Sitecore Search, with support for pagination, sorting, and request cancellation built in. Type-safe parameters and responses throughout, with generic field support so you're not fighting the type system when your schema diverges from defaults.
On the React side, two hooks: `useSearch` for standard paginated queries with automatic state management, and `useInfiniteSearch` for infinite scroll patterns with a `loadMore` function. Both handle request cancellation and expose request status, which is the kind of thing you'd normally have to wire up yourself.
What this means in practice: if you were previously integrating Sitecore Search through the Search or Cloud SDKs, this is the path forward. Centralizing it into the Content SDK makes sense, it keeps the dependency graph simpler and aligns with how Sitecore is consolidating the composable DXP surface area. As you might know Search is now part of the unified SitecoreAI offering (among the others products) even in the escentials tier.
Worth noting: I've written extensively about Sitecore Search architecture, the discovery phase decisions that define how well your integration holds up over time. That work doesn't change with this release, but where you wire the client does.
Analytics & Personalize: Moved from CloudSDK
Same as with Search, the `core`, `events`, and `personalize` packages have been migrated out of CloudSDK and into the Content SDK. The new packages are `analytics-core`, `events`, and `personalize`, and they're initialized through a new `initContentSdk` function.
This is a consolidation move. CloudSDK was always a bit of an awkward dependency to carry separately, and pulling it into Content SDK proper makes the initialization story cleaner. One entry point, one SDK to version, one place to look when something goes wrong.
If you were using CloudSDK's analytics and personalization capabilities, this is a breaking change from a packaging perspective, but the functional behavior is the same. You'll need to update imports and swap initialization logic. The upgrade guide covers the specifics.
From an architecture standpoint, this is the right call. Personalization isn't an add-on anymore, it's part of the core delivery runtime. The SDK structure should reflect that.
Next.js 16 + Turbopack
The SDK has upgraded to Next.js 16 as the minimum required version (`^16.0.0`), and ships with two Next.js 16 capabilities enabled by default: Cache Components and Turbopack File System Caching.
Cache Components are one of the more interesting additions in Next.js 16, they let you cache the output of a component across requests rather than re-running it every time, which makes a material difference for expensive server-side renders. Turbopack File System Caching accelerates local development builds significantly, if you're running a large Content SDK project locally, you'll feel this. Note that the cache components feature is not enabled by default.
The breaking change here is worth flagging clearly: `middleware.ts` is renamed to `proxy.ts` with an updated function signature. If you have middleware logic, and most production Content SDK apps do, you'll need to rename the file and update the signature. This is a straightforward change, but it will break things if you miss it, and it won't fail loudly in every environment.
Also gone: `images.domains`. Next.js deprecated this in favor of `remotePatterns` some time ago, and v2.0.0 removes it entirely. If you're still using `images.domains` in your Next.js config, update it before you upgrade.
Agent Skills
This one is interesting, and a bit different in nature from the rest.
The SDK now ships a `.agents/skills/` directory with SKILL.md files per capability, aligned with the agentskills.io convention. Each skill file describes a specific capability with when-to-use guidance, hard rules, and stop conditions for AI coding assistants.
Scaffolded apps via `create-content-sdk-app` include these out of the box for both Pages Router and App Router templates.
The intent is to give AI coding tools like Cursor, Copilot, Claude, etc structured, reliable context about how the SDK works, what the conventions are, and when not to do something. Rather than letting an AI assistant infer how Content SDK works from general Next.js knowledge, the skills give it accurate, SDK-specific guidance.
Is this a feature developers will notice day-to-day? Probably not immediately, but they should! if they're using AI-assisted coding properly and following good practices. Anyway it's a meaningful signal that Sitecore is thinking about AI-assisted development as part of the SDK's design surface, not just something that happens around the edges. As AI coding tools become more central to how teams build, having well-authored skills will matter. Having this baked into the template means you don't have to build it yourself.
Custom Edge Hostnames
New environment variable: `SITECORE_EDGE_PLATFORM_HOSTNAME` (or `NEXT_PUBLIC_SITECORE_EDGE_PLATFORM_HOSTNAME` for Next.js). This replaces the old `SITECORE_EDGE_URL`, which is now gone.
A new `rewriteMediaUrls` option accompanies it. When set to `true`, layout media URLs are rewritten to point to the custom Edge hostname. When set to a function, you can apply a custom string transformer, useful if your CDN setup has path conventions that differ from the default.
This matters for projects running behind custom domains or enterprise CDN configurations where the default Edge URL doesn't match the routing topology. Previously, this required workarounds. Now it's a first-class concern in the SDK config.
The breaking part: `SITECORE_EDGE_URL` is gone. If it's referenced anywhere in your environment config or CI pipelines, update it before you upgrade. These kinds of silent env var renames are easy to miss in a staging environment and then surface in production.
Custom Query Parameters on Editing Routes
You can now pass custom query parameters to `/api/editing/render` handlers. A small addition, but useful in practice.
If you've built custom editing integrations or extended the render pipeline in any way, you've probably run into the constraint of not being able to forward arbitrary context through to the render. This removes that limitation cleanly.
Explicit Content-Type on Editing Render Route (Pages Router)
The editing render route response now explicitly sets `Content-Type: text/html; charset=utf-8`. Pages Router only.
This is a bug fix as much as a feature, certain reverse proxies and response parsers were misinterpreting the content type, which caused editing rendering issues in specific infrastructure configurations. If you've been debugging intermittent editing problems in environments behind a proxy, this may be what fixes it.
Breaking Changes: What Needs Your Attention
Let me be direct about the upgrade surface, because 2.0 has more of it than previous minor releases.
- Node.js 24.x is now required. If your CI/CD pipeline is running on 20 or 22, update it before anything else. This will break your build silently in some configurations.
- `@sitecore-content-sdk/content` is decoupled from `@sitecore-content-sdk/core`. This is listed as a breaking change and there's a detailed upgrade guide. Worth reading before you start, the implications depend on how you've structured your content fetching layer.
- `SITECORE_EDGE_URL` is removed. Covered above, but worth repeating.
- `middleware.ts` → `proxy.ts` with a new function signature.
- `disableSuspense` now defaults to `true` on Placeholder. The old default forced Suspense across all components, which could negatively impact performance metrics. If you've been relying on Suspense behavior from Placeholder implicitly, you'll need to opt back in explicitly. This is a performance improvement by default, but it's a behavioral change that could surface unexpectedly if you're not expecting it.
- `withSitecore` HOC's `updatePage` prop is renamed to `setPage`, and the HOC itself is now marked deprecated. The direction is `useSitecore` hook. Not urgent to refactor immediately, but don't extend existing usage.
- `useLoadImportMap` and `useComponentMap` HOCs are removed. The Sitecore context is now accessed via `useSitecore`. If you have components built on those HOCs, they'll need updating.
- Redirects behavior changes with the `isLanguagePreserved` flag. Previously, a redirect from `/da/source` to `/target` would resolve to `/da/target` when the default locale wasn't `da`. Now it resolves to `/target` using the default locale, unless the "Shall language be preserved upon redirect?" flag is explicitly enabled. If your SXA redirect maps depend on locale-preserving behavior, test this carefully before deploying.
Should You Upgrade Now?
For new projects: yes, you start on 2.0. That's not a question.
For existing Content SDK projects: this depends on what you're running and how much of the breaking change surface affects you. Run through the checklist:
- Are you on Node.js 24.x?
- Have you replaced `SITECORE_EDGE_URL`?
- Do you have `middleware.ts`?
- Do you use `useLoadImportMap`, `useComponentMap`, or `withSitecore`?
- Do you depend on `images.domains`?
- Do you have Suspense-sensitive Placeholder behavior?
- Do you have locale-sensitive SXA redirects?
If you're clean on most of those, the upgrade is straightforward and worth doing, especially if you want the Search package, the analytics consolidation, or Next.js 16 performance improvements.
If you hit several of those, plan for a proper upgrade sprint, not a Friday afternoon dependency bump :)
The Bigger Picture
What 2.0 signals is that the Content SDK has reached a point where Sitecore is willing to make real breaking changes in service of a cleaner architecture. That's a maturity indicator. You don't clean up a product's foundation unless you're committing to it long-term.
The consolidation of CloudSDK analytics, the first-party Search package, the Agent Skills infrastructure, these aren't features that make for good conference demos. They're the kind of structural work that makes the platform better to build on over time.
And as a reminder: JSS deprecation is June 2026. If you're still on JSS, the Content SDK 2.0 upgrade guide isn't your immediate concern, getting off JSS is. But once you're there, 2.0 is where you want to land.
Stay tuned! I'll share lessons learned once our teams have gone through the upgrade.
