SDK Selection

Read the target project’s installed packages and lockfile before giving version or migration advice. Keep packages in the same dependency graph compatible; React Native can follow a different release cadence from the Web, React, Next.js, and Node packages.

Decision Table

Recommended SDK: @contentful/optimization

Pick the application-facing package by runtime:

• React Web: @contentful/optimization-react-web
• Next.js App Router or Pages Router: @contentful/optimization-nextjs
• Browser without React: @contentful/optimization-web
• Node.js and stateless server evaluation: @contentful/optimization-node
• React Native: @contentful/optimization-react-native

The integration model is runtime-specific:

• React Web uses OptimizationRoot or an explicitly owned instance with OptimizationProvider.
• Next.js uses the bound factory for its router; do not assemble it from generic client and server exports.
• Web and Node use ContentfulOptimization; Node creates request-scoped evaluation with forRequest().
• React Native uses its asynchronous root or an explicitly owned mobile instance.

Load optimization-shared.md together with exactly the runtime references selected by optimization-overview.md.

Existing Legacy Deployments: @ninetailed/experience.js

Legacy references exist to support deployed systems that still use:

• NinetailedProvider
• <Experience> or <Personalize>
• @ninetailed/experience.js-utils-contentful
• insights, SSR, preview, privacy, or destination plugins
• the ntaid browser cookie and legacy page, track, or identify calls

For those systems, preserve compatible package majors and follow the project’s established provider, plugin, and rendering patterns. Load sdk-legacy-guide.md only when old packages or APIs are present, or when the user explicitly asks about an existing legacy deployment.

Do not describe the legacy deployment as broken merely because it has not migrated. Fix or extend it in place when that is the requested scope. A migration is a separate change because provider lifecycle, consent, identity, persistence, rendering, and tracking contracts differ.

Architecture Guidance

Choose architecture after selecting the SDK and runtime, from the project’s real rendering model.

The client-only tradeoff

Client-only evaluates personalization in the browser after hydration, so the page renders the baseline (unpersonalized) content first and then swaps to the selected variant. The visitor sees either a flash of baseline content or a hidden/skeleton slot until evaluation resolves. This matters more for personalization than for a small A/B tweak, because the whole point is to show the right content — and it is most visible above the fold.

The flash-vs-caching tradeoff

The two architectures trade off flash against caching; neither gives both:

• Client-only keeps the page HTML static and CDN-cacheable — the server does no per-visitor work — but flashes the baseline before the variant resolves.
• Hybrid SSR removes the flash by resolving the variant on the server, but a route that resolves personalization server-side reads request headers/cookies and therefore renders dynamically per request. That route is not shared-CDN-cacheable across visitors and is not compatible with static/ISR output. Only the personalized resolution is per-request: routes that are not personalized, and the raw baseline Contentful data, can still follow an application cache policy. (See the “Server and cache boundaries” section of the App Router runtime reference.)

Prefer server-side where the framework and pipeline support it

Lean toward hybrid SSR (server preflight resolves the variant before markup is sent, then the client hydrates and takes over) when all of these hold:

• the framework can render on the server (Next.js App or Pages Router, Remix),
• the app already fetches content at the page or server level, and
• rendering the personalized routes per request (rather than serving shared cached HTML) is acceptable.

In that case the framework adapter handles the server-to-client handoff, so it is usually a small step rather than a rewrite — you are trading the personalized routes’ shared cacheability for the removal of the flash.

Choose client-only when the framework is client-only (Gatsby, Create React App, Vite React, React Native), when the app fetches only in the browser and the smaller change is preferred, when the personalized surface is below the fold or non-critical, or when the route’s CDN cacheability must be preserved. Do not push a client-fetched app to convert to SSR purely for this setup — recommend what fits the app today, name the flash-vs-caching tradeoff honestly, and note that moving personalization resolution server-side later is the path to eliminate the flash.

Server-only remains a weak fit when the product needs browser event collection, component insights, or reliable experiment reporting.

Communication Rule

Lead new work with @contentful/optimization without presenting both SDKs as equivalent choices. Mention @ninetailed/experience.js only when the detected codebase or the user’s maintenance task makes it relevant.