Choose the right SDK

Overview

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.

Recommendation

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.

Decision table

Use this table to choose the primary package and the next integration guide:

Alternatives

• Browser preview panel - Add @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.
• Core SDK - Use @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.
• API client - Use @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.
• API schemas - Use @contentful/optimization-api-schemas when you need shared runtime validation schemas or inferred TypeScript types for Contentful CDA, Experience API, and Insights API payloads.
• Native JavaScript bridge - @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.

Follow-up guides

After choosing the package, follow the matching guide: