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. Next.js App Router apps use @contentful/optimization-nextjs/app-router; it provides createNextjsAppRouterOptimization(), an automatic factory that returns app-local bound OptimizationRoot, OptimizationProvider, OptimizedEntry, and route trackers for Server and Client Components. Next.js Pages Router apps use @contentful/optimization-nextjs/pages-router plus @contentful/optimization-nextjs/pages-router/server for getServerSideProps. The Next.js package root is intentionally not an import path; use /client, /server, /request-handler, /esr, and /tracking-attributes subpaths for lower-level control. 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.

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, we recommend the consumer-owned contentful.js path when the app already uses that client. Create the delivery client in your app, pass it to the Optimization SDK as contentful: { client, defaultQuery?, cache? }, then fetch optimized entries by entry ID through SDK helpers or framework entry props. When a route knows several IDs, managed prefetch can batch uncached entries through getEntries() on that client, split into 100-ID chunks for large fetches. Manual baseline-entry fetching plus resolveOptimizedEntry() remains supported when the app needs full delivery control or a non-contentful.js flow.

For custom JavaScript runtimes or framework adapters where no official package fits, use Core plus the @contentful/optimization-core/entry-source subpath for managed baselineEntry | entryId lifecycle. Keep using the highest-level SDK when one fits; Core does not provide rendering, runtime-specific tracking, consent UI, or framework integration.

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 source lifecycle 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: