Guides

Use this index to pick the guide that matches your SDK runtime. Start with package selection when you are unsure which SDK layer belongs in your app.

Start here

Choosing the right SDK - Choose the SDK package and runtime layer for your app.

Integration guides

Server and web SDK guides are listed before native and mobile SDK guides.

Server and web SDKs

Guide	Runtime or app type	Package
Node SDK	Node server, custom SSR server, or server-side function	`@contentful/optimization-node`
Web SDK	Browser app, static site, multi-page app, SPA, Angular app, or custom frontend runtime	`@contentful/optimization-web`
React Web SDK	React browser app	`@contentful/optimization-react-web`
Next.js SDK in App Router	Next.js App Router app	`@contentful/optimization-nextjs`
Next.js SDK in Pages Router	Next.js Pages Router app with `getServerSideProps` request handoff	`@contentful/optimization-nextjs`

Native and mobile SDKs

Native and mobile SDK guides route to beta SDK surfaces.

Guide	Runtime or app type	Package
React Native SDK	React Native or Expo mobile app	`@contentful/optimization-react-native`
iOS SDK in SwiftUI	Native iOS app built with SwiftUI	`ContentfulOptimization` Swift Package
iOS SDK in UIKit	Native iOS app built with UIKit	`ContentfulOptimization` Swift Package
Android SDK in Jetpack Compose	Native Android app built with Jetpack Compose	`com.contentful.java:optimization-android`
Android SDK in Android Views	Native Android app built with Android Views or XML layouts	`com.contentful.java:optimization-android`

experience.js migration guides

Use these guides when an app already uses @ninetailed/experience.js packages and you are replacing that integration with the Optimization SDK Suite. Start with the Contentful model guide when legacy nt_* fields or mapper utilities feed personalized rendering.

Guide	Legacy integration type	Target path
Contentful model migration	Legacy Ninetailed-authored entries, `nt_*` fields, mapper utilities	Optimization-authored experiences and target entry resolution
Web SDK migration	Plain browser, static site, SPA, Angular, or custom JavaScript runtime	`@contentful/optimization-web`
React Web migration	React provider, hook, component, or flag surfaces	`@contentful/optimization-react-web`
Next.js migration path choice	Legacy Next.js, SSR plugin, ESR, or manual hybrid wiring	App Router, Pages Router, or manual Node/Web path
Next.js App Router migration	Next.js app moving to App Router	`@contentful/optimization-nextjs/app-router/server`, `@contentful/optimization-nextjs/app-router/client`
Next.js Pages Router migration	Pages Router app with legacy SSR/plugin wiring	`@contentful/optimization-nextjs/pages-router`
Node, SSR, and ESR migration	Server API-client, SSR, ESR, or manual handoff code	Node SDK, framework SDK, or manual Node/Web hybrid
Plugins and preview migration	Legacy privacy, analytics, insights, or preview plugins	Target consent, event streams, forwarding, and preview panel

Supplemental guides

Using Contentful GraphQL data with the Optimization SDKs - Query Optimization-owned fields through Contentful GraphQL, adapt GraphQL-shaped entries for the resolver, and keep your app's GraphQL client and cache.
Building a custom JavaScript Optimization adapter - Build a low-level adapter only when no official SDK package fits your JavaScript runtime or framework.
Rendering personalized Next.js routes with static, ISR, and edge handoffs - Choose cache-safe handoff patterns for Next.js static, ISR, edge, and analytics-only routes after integrating the Next.js SDK.
Forwarding Optimization SDK context to analytics and tag-management tools - Forward optimization context to analytics, tag-management, customer-data, or product-analytics tools after SDK integration.