| title | Guides | |||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| children |
|
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.
- Choosing the right SDK - Choose the SDK package and runtime layer for your app.
Server and web SDK guides are listed before native and mobile SDK guides.
| 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 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 |
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 |
- 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.