Use this guide when you need to select the Optimization SDK package or native package that matches an application runtime before following an integration guide.
Choose the highest-level SDK that matches the app runtime. Framework and native SDKs own the runtime-specific setup around providers, hooks, screen or route tracking, persistence, preview tooling, and platform defaults. Use lower-level packages only when you are building SDK layers, tooling, tests, or first-party integrations that need shared SDK primitives or raw API access.
For mixed server and browser applications, use the adapter when one exists. A Next.js App Router app
installs @contentful/optimization-nextjs; /app-router/server is its normal Server Component
import subpath. /app-router/client owns the Client Component binder and the direct
NextAppAutoPageTracker export; use its binder when the app needs bound Client Components. These
are entrypoints in one package, not separate packages to install.
Next.js Pages Router apps install the same package and use its /pages-router entrypoints.
Non-Next.js server-rendered apps can combine @contentful/optimization-node on the server with
@contentful/optimization-web or @contentful/optimization-react-web in the browser.
After choosing App Router or Pages Router, use Rendering personalized Next.js routes with static, ISR, and edge handoffs when individual Next.js routes need static generation, App Router Cache Components, Pages Router ISR, Edge runtime route handlers, or analytics-only handoff patterns.
Angular, Vue, Svelte, Web Components, and custom browser framework apps use
@contentful/optimization-web. Nest.js and other Node server frameworks use
@contentful/optimization-node unless the app is a Next.js App Router or Pages Router app covered
by the Next.js adapter.
For JavaScript SDKs, pass an existing app-owned contentful.js client when the SDK should manage
entry fetching. Keep manual fetching when the app needs full delivery control.
Use Core only when building a custom runtime or framework adapter and no official package fits.
For mobile apps, choose @contentful/optimization-react-native when the mobile app is built with
JavaScript or TypeScript in React Native. Choose the native iOS or Android SDK only for
platform-native apps that can accept beta native API and setup changes.
The React Native, iOS, and Android SDKs are in beta. Plan for breaking changes while adopting native SDKs.
Use this table to choose the primary package and the next integration guide:
| Reader need | Choose | Why | Next guide |
|---|---|---|---|
| Nest.js app, Node server, server function, or SSR layer outside the Next.js adapter | @contentful/optimization-node |
It provides request-scoped profile evaluation, event emission, managed fetching and prefetching by ID or content type and slug, entry resolution, and Node caching guidance. | Integrating the Optimization Node SDK in a Node app |
| Angular, Vue, Svelte, Web Components, non-React browser app, or custom browser framework app | @contentful/optimization-web |
It owns browser consent, anonymous ID persistence, managed fetching and prefetching by ID or content type and slug, interaction tracking, event delivery, and Web Components. | Integrating the Optimization Web SDK in a web app |
| React browser app outside Next.js integration | @contentful/optimization-react-web |
It adds React providers, hooks, route tracking, optimized entry rendering from entryId or a content-type/slug managedEntry, interaction tracking, and live updates to the Web SDK. |
Integrating the Optimization React Web SDK in a React app |
| Next.js App Router app with server-personalized first paint and browser re-resolution after hydration | @contentful/optimization-nextjs |
Use /app-router/server for Server Components; /app-router/client owns the client binder and direct App Router tracker. |
Integrating the Optimization Next.js SDK in a Next.js App Router app |
Next.js Pages Router app with getServerSideProps personalization |
@contentful/optimization-nextjs/pages-router plus /pages-router/server |
Its /pages-router components and /pages-router/server request handoff helper pass browser handoff through pageProps and avoid duplicate initial page events. |
Integrating the Optimization Next.js SDK in a Next.js Pages Router app |
| Custom JavaScript runtime or framework adapter where no official SDK fits | @contentful/optimization-core plus @contentful/optimization-core/entry-source |
Core provides shared state and resolution. The entry-source subpath manages baselineEntry, entryId, or content-type/slug managedEntry; adapters own rendering, tracking, and runtime policy. |
Building a custom JavaScript Optimization adapter |
| React Native app | @contentful/optimization-react-native |
It provides a stateful JavaScript mobile runtime with React providers, hooks, OptimizedEntry, screen tracking, optional offline-aware delivery, and preview-panel support. |
Integrating the Optimization React Native SDK in a React Native app |
| Native iOS app built with SwiftUI that accepts beta native API and setup changes | ContentfulOptimization Swift Package |
It provides native Swift APIs, SwiftUI helpers, persistence, networking, lifecycle handling, screen tracking, entry rendering, and preview-panel UI. | Integrating the Optimization iOS SDK in a SwiftUI app |
| Native iOS app built with UIKit or direct client ownership that accepts beta native API and setup changes | ContentfulOptimization Swift Package |
It exposes the same native iOS runtime through direct client APIs and UIKit-compatible preview, screen tracking, and entry-rendering patterns. | Integrating the Optimization iOS SDK in a UIKit app |
| Native Android app built with Jetpack Compose that accepts beta native API and setup changes | com.contentful.java:optimization-android |
The Android AAR includes the stateful Kotlin client, Compose UI helpers, screen tracking, entry optimization, preview controls, and offline event delivery. | Integrating the Optimization Android SDK in a Jetpack Compose app |
| Native Android app built with Android Views or XML layouts that accepts beta native API and setup changes | com.contentful.java:optimization-android |
The same Android AAR includes Android Views helpers such as OptimizationManager, OptimizedEntryView, ScreenTracker, preview controls, and the stateful client. |
Integrating the Optimization Android SDK in an Android Views app |
@contentful/optimization-web-preview-panel to a Web SDK or React
Web SDK integration when the browser app needs author preview overrides. It attaches to a Web SDK
instance and reads definitions from an existing Contentful client or pre-fetched audience and
experience entries; it is not a standalone SDK.@contentful/optimization-core when building or maintaining an SDK layer that
needs the shared state machine, event builders, queues, resolvers, interceptors, or preview
support. Use @contentful/optimization-core/entry-source only when building an adapter that must
manage baselineEntry, entryId, or content-type/slug managedEntry sources before resolution.
Application integrations start with a platform SDK.@contentful/optimization-api-client when building SDK layers, tooling,
tests, or first-party integrations that need direct Experience API or Insights API transport
without SDK state, consent handling, event builders, entry resolution, tracking, or platform
defaults.@contentful/optimization-api-schemas when you need shared runtime
validation schemas or inferred TypeScript types for Contentful CDA, Experience API, and Insights
API payloads.@contentful/optimization-js-bridge is internal bridge
infrastructure for the native iOS and Android SDKs. Native applications use the
ContentfulOptimization Swift Package or com.contentful.java:optimization-android instead.After choosing the package, follow the matching guide: