Contentful Personalization & Analytics

Optimization SDK Suite

Introduction

A pnpm monorepo hosting a suite of SDKs, supporting libraries, and reference implementations for Contentful Personalization and Analytics products.

What is Contentful?

Contentful provides content infrastructure for digital teams to power websites, apps, and devices. Unlike a CMS, Contentful was built to integrate with the modern software stack. It offers a central hub for structured content, powerful management and delivery APIs, and a customizable web app that enables developers and content creators to ship their products faster.

Table of Contents

• Choosing a package
• Published packages
• Native and planned SDKs
• Reference implementations
• Repository layout
• Get involved
• License
• Code of conduct

Choosing a package

If you are deciding which SDK or library belongs in your application, start with Choosing the right SDK.

For step-by-step implementation docs, start with the Guides index. For behavior explanations, start with the Concepts index.

If you are upgrading existing Optimization packages from v1, follow Migrate Optimization SDK packages from v1 to v2 before changing package versions.

Package README files listed below are package-level guides and API surface summaries. For packages included in the TypeDoc build, generated reference documentation remains the source of truth for exported API signatures. The Next.js package is not yet included there; use its package README for that surface.

Published packages

The published package surface is intentionally layered. The table below is a package inventory and high-level role summary.

Package	Kind	Runtime	Role	Package README
@contentful/optimization-web	Environment SDK	Browser	Stateful browser SDK for optimization, tracking, and consent	Web SDK
@contentful/optimization-react-web	Framework SDK	React on the web	React integration layer on top of the Web SDK	React Web SDK
@contentful/optimization-nextjs	Framework SDK	Next.js	Next.js adapter for explicit App Router and Pages Router bound components, SSR, client tracking, and request composition	Next.js SDK
@contentful/optimization-node	Environment SDK	Node.js	Stateless Node SDK for server-side and SSR integrations	Node SDK
@contentful/optimization-react-native	Environment SDK	React Native	React Native SDK for mobile applications	React Native SDK
@contentful/optimization-web-preview-panel	Tooling package	Browser	Preview tooling package for existing Web SDK instances	Web Preview Panel
@contentful/optimization-core	Shared SDK foundation	Runtime-agnostic	Shared optimization foundation, CDA schemas, and aggregate schema pass-throughs for runtime adapters and SDK layers	Core SDK
@contentful/optimization-api-client	Universal library	Runtime-agnostic	Direct Experience API and Insights API transport with their validation schemas	API Client
@contentful/optimization-api-schemas	Compatibility facade	Runtime-agnostic	Deprecated compatibility facade for the historical combined API-schema root surface	API Schemas

General selection rules:

• We recommend starting application code with an environment SDK or framework SDK.
• @contentful/optimization-core is the shared foundation for runtime adapters and SDK layering. Its /api-schemas entry point owns Contentful CDA schemas and provides an aggregate schema surface for SDK layers.
• @contentful/optimization-api-client is the lower-level Experience API and Insights API transport. Its /api-schemas entry point owns the corresponding validation schemas.
• @contentful/optimization-api-schemas remains available only for compatibility with the historical combined root surface. Use the migration guidance in its README instead of adding new imports from this package.

Native and planned SDKs

React Native support is available through @contentful/optimization-react-native.

Native iOS support is also present in this repository as a Swift Package under packages/ios, backed by the shared @contentful/optimization-js-bridge adapter and the iOS reference app.

Native Android support is also present as a Kotlin Android library under packages/android, published as the Maven AAR com.contentful.java:optimization-android, backed by the shared @contentful/optimization-js-bridge adapter and the Android reference app.

The following framework SDKs are planned but are not published from this repository:

• Nest.js SDK
• Angular SDK
• Svelte SDK
• Vue SDK

Reference implementations

Reference implementations exist to exercise critical flows end to end and to document common usage patterns with intentionally minimal application code.

• Web Vanilla - static browser integration for the Web SDK
• Web SDK Angular - Angular integration using the Web SDK directly
• React Web - primary React browser integration using the official React Web SDK package
• Web SDK React Adapter - adapter-based React example built directly on top of the Web SDK
• Node SSR Only - server-rendered integration using the Node SDK
• Node SSR + Web Vanilla - split server/browser flow using Node and Web SDKs together
• Next.js SDK App Router - Next.js App Router first-paint SSR with browser-side takeover after hydration
• Next.js SDK Pages Router - Next.js Pages Router integration using getServerSideProps state handoff
• React Native - mobile application integration for Android and iOS targets
• iOS Reference App - native app and XCUITest surface for current iOS bridge and preview-panel scenarios
• Android Reference App - native Compose and XML Views app shells plus Maestro E2E coverage for Android bridge and preview-panel scenarios

Repository layout

• packages/: published SDKs and supporting libraries
• implementations/: reference applications used for examples and E2E coverage
• lib/: shared internal workspace packages such as mocks and build tooling
• documentation/: authored supporting documentation published alongside TypeDoc
• docs/: architecture decision records
• site/: generated TypeDoc and GitHub Pages output; not source of truth

Get involved

We appreciate any help on our repositories. For more details about how to contribute see our CONTRIBUTING document.

License

This repository is published under the MIT license.

Code of conduct

We want to provide a safe, inclusive, welcoming, and harassment-free space and experience for all participants, regardless of gender identity and expression, sexual orientation, disability, physical appearance, socioeconomic status, body size, ethnicity, nationality, level of experience, age, religion (or lack thereof), or other identity markers.

Read our full Code of Conduct.