Setting the file. One moment.
Skill 09 · Contentful Personalization
Subchapter 9.20
references/package-versions.mdMarkdown5 KBView on GitHub
Use @contentful/optimization-* for new integrations. The @ninetailed/experience.js* packages
remain documented only for diagnosing, repairing, or extending repositories that already use them.
@contentful/optimization-*Read versions from the target project’s lockfile. Keep packages in the same dependency graph compatible; do not force React Native to the same version as the Web family because it can use a different release cadence.
Install the narrowest package for your runtime:
| Package | Runtime / Use |
|---|---|
@contentful/optimization-react-web | React on the web (React, Gatsby, Remix, Vite, CRA) |
@contentful/optimization-nextjs | Next.js App Router or Pages Router adapter |
@contentful/optimization-web | Non-React browser apps and custom adapters |
@contentful/optimization-node | Stateless server / SSR / server functions |
@contentful/optimization-react-native | React Native mobile apps |
| Package | Purpose |
|---|---|
@contentful/optimization-web-preview-panel | Author preview tooling for an existing Web SDK instance |
@contentful/optimization-core | Shared foundation — not used directly by app code |
@contentful/optimization-api-client | Direct Experience API + Insights API client |
@contentful/optimization-api-schemas | Zod Mini validation schemas and inferred types |
@contentful/optimization-react-web (wraps the Web SDK transitively).@contentful/optimization-nextjs; create the bound integration from
/app-router.@contentful/optimization-nextjs; create separate bindings from
/pages-router and /pages-router/server.@contentful/optimization-web.@contentful/optimization-node.@contentful/optimization-core directly instead of an environment or framework SDK.@contentful/optimization-node + @contentful/optimization-react-web by hand in Next.js
instead of using the @contentful/optimization-nextjs adapter.Install or change these packages only when maintaining a detected legacy deployment. Do not use
them to start a new integration. See sdk-legacy-guide.md for the legacy API.
| Package | Purpose | Required |
|---|---|---|
@ninetailed/experience.js | Core SDK — profile management, experience resolution | Yes |
Install exactly one based on your framework:
| Package | Framework |
|---|---|
@ninetailed/experience.js-next | Next.js (App Router and Pages Router) |
@ninetailed/experience.js-react | React (non-Next.js) |
@ninetailed/experience.js-gatsby | Gatsby |
@ninetailed/experience.js-remix | Remix |
| Package | Purpose |
|---|---|
@ninetailed/experience.js-plugin-insights | Built-in analytics dashboard |
@ninetailed/experience.js-plugin-preview | Visual preview in Contentful |
@ninetailed/experience.js-plugin-google-tagmanager | GTM event forwarding |
@ninetailed/experience.js-plugin-segment | Segment event forwarding |
@ninetailed/experience.js-plugin-contentsquare | Contentsquare integration |
@ninetailed/experience.js-plugin-ssr | Server-side rendering support |
@ninetailed/experience.js-* packages should use the same major version.@ninetailed/experience.js-react instead of -next in a Next.js project.