Contentful Personalization & Analytics

Optimization Node SDK

The Optimization Node SDK implements stateless server-side optimization behavior on top of the Optimization Core SDK. Use it for server rendering, server functions, and Node services that need request-scoped profile evaluation or event emission.

If you are integrating a Node application, start with Getting Started, then use Integrating the Optimization Node SDK in a Node app for the step-by-step flow. This README keeps the package orientation and common setup options close at hand; generated reference documentation remains the source of truth for exported API signatures.

Getting started

Install using an NPM-compatible package manager, pnpm for example:

pnpm install @contentful/optimization-node
Copy

Import the Optimization class; both CJS and ESM module systems are supported, ESM preferred:

import ContentfulOptimization from '@contentful/optimization-node'
Copy

Create the SDK once per module or process, then pass request-scoped event context inside each incoming request:

const optimization = new ContentfulOptimization({
  clientId: 'your-client-id',
  environment: 'main',
  contentfulLocales: {
    default: 'en-US',
  },
})

async function renderRequest(req: { headers: { 'accept-language'?: string } }, profileId: string) {
  const { contentfulLocale, eventLocale } = optimization.resolveRequestLocale(req)
  const requestOptions = contentfulLocale ? { locale: contentfulLocale } : undefined

  return await optimization.page(
    { locale: eventLocale, profile: { id: profileId } },
    requestOptions,
  )
}
Copy

When to use this package

Use @contentful/optimization-node for server-side rendering, server functions, and Node services that need stateless profile evaluation or event emission. Use the Web or React Web SDK alongside it when browser-side consent, anonymous ID persistence, automatic interaction tracking, or live updates are part of the same application.

Common configuration

The Node SDK is stateless. It does not maintain consent, profile, or browser persistence state between requests.

Common api options:

Request-scoped Experience options belong in the final argument to stateless event methods:

Common fetchOptions are fetchMethod, requestTimeout, retries, intervalTimeout, onFailedAttempt, and onRequestTimeout. Default retries intentionally apply only to HTTP 503 responses.

Use contentfulLocales.default for single-locale apps. For apps that match request locale input to multiple Contentful locales, keep default as the fallback and list the supported Contentful locale codes:

const optimization = new ContentfulOptimization({
  clientId: 'your-client-id',
  contentfulLocales: {
    default: 'en-US',
    supported: ['en-US', 'de-DE', 'fr-FR'],
  },
})
Copy

Copy contentfulLocales.default and optional contentfulLocales.supported from Contentful locale settings or the CMA locale list. The returned contentfulLocale, when present, is the configured Contentful locale code to use for CDA fetches and the Experience API request option. Use eventLocale separately in event context. Merge tags that reference localized profile fields such as location.city and location.country then resolve in a language consistent with the rendered content. See Locale handling in the Optimization SDK Suite for the full locale model.

For every option, callback payload, and exported type, use the generated Node SDK reference.

Core workflows

Request-scoped events

Build event context from the incoming request, then call page(), identify(), screen(), track(), or sticky trackView() when optimization data is needed:

import type { Request } from 'express'

app.get('/products/:slug', async (req, res) => {
  const { contentfulLocale, eventLocale } = optimization.resolveRequestLocale(req)
  const requestOptions = contentfulLocale ? { locale: contentfulLocale } : undefined
  const optimizationData = await optimization.page(
    {
      locale: eventLocale,
      profile: { id: req.cookies.profileId },
      properties: { path: req.path },
    },
    requestOptions,
  )

  res.render('product', { optimizationData })
})
Copy

In stateless runtimes, Insights-backed methods require a profile for delivery. Non-sticky trackView, trackClick, trackHover, and trackFlagView require payload.profile.id.

Content resolution

Fetch Contentful entries in your application layer, then resolve variants with returned optimization data:

const resolvedEntry = optimization.resolveOptimizedEntry(
  baselineEntry,
  optimizationData?.selectedOptimizations,
)
Copy

Fetch entries with one CDA locale in the app layer. For localized apps, configure contentfulLocales, then use the contentfulLocale returned by resolveRequestLocale() for CDA fetches and the per-call { locale } request option so MergeTags that read localized profile fields match the entry language. When contentfulLocale is absent because no contentfulLocales config is present, omit the CDA and Experience API locale options intentionally. Do not pass all-locale CDA responses from withAllLocales or locale=* into resolveOptimizedEntry(); the resolver expects direct single-locale field values. See Entry personalization and variant resolution for the entry contract and Locale handling in the Optimization SDK Suite for request locale behavior.

Use getMergeTagValue() for Contentful Rich Text merge tags and getFlag() for Custom Flags. If a merge tag references localized profile fields such as location.city or location.country, its resolved value follows the localized profile data returned by the Experience API. The Node SDK is stateless, so getFlag() does not automatically emit flag-view tracking.

Caching guidance

Cache raw Contentful delivery payloads in your application layer, not profile-evaluated SDK event results.

The Node SDK integration guide covers request context, profile persistence, Contentful entry resolution, and hybrid Node + browser setups in detail.

Development harness

The package-local dev harness runs from packages/node/node-sdk/dev/ and reads .env from this package directory.

1. Start from .env.example and create or update packages/node/node-sdk/.env.

2. Prefer the repo-standard PUBLIC_... variable names shown in .env.example.

3. Start the harness from the repo root:

   pnpm --filter @contentful/optimization-node dev
   Copy

Related

• Integrating the Optimization Node SDK in a Node app - step-by-step server-side integration guide
• Node SDK generated reference - exported API reference
• Node reference implementation - server-rendered implementation using request-scoped SDK calls
• Node + Web reference implementation - hybrid SSR and browser implementation
• Optimization Web SDK - browser SDK used when the same application also needs client-side consent, persistence, tracking, or live updates