Contentful Personalization & Analytics

Node SDK SSR + Web SDK Vanilla JS Reference Implementation

This is a reference implementation using both the Optimization Node SDK and Optimization Web SDK, and is part of the Contentful Optimization SDK Suite.

What this demonstrates

Use this implementation when you need a hybrid SSR/browser example. It demonstrates a stateless Node SDK server flow, a stateful Web SDK browser flow, consent-aware cookie-based profile continuity between them, and local mock API usage for end-to-end validation.

On the server side, the stateless Node SDK is created once at module load. Each request binds request-scoped options with sdk.forRequest(...), then calls stateless event methods on the returned request object. The demo stores application-owned consent in a server-readable cookie and writes the shared anonymous ID cookie only when consent permits profile continuity. When app consent is missing or denied, the server clears the shared anonymous ID cookie, skips Node SDK event calls, and lets the browser render baseline entries.

The goal of this reference implementation is to illustrate the usage of cookie-based communication in both the Node and Web SDKs, which is an important component of many server-side/client-side hybrid SSR and ESR solutions.

CDA locale handling

The server and browser share one APP_LOCALE. Server code passes it to the Node SDK request context with sdk.forRequest({ locale: APP_LOCALE }) and uses it when building event context. Browser code passes the same value as the Web SDK top-level locale and directly to Contentful CDA entry fetches. Do not use contentful.js withAllLocales or raw CDA locale=* for entries passed to SDK resolution; the resolver expects direct single-locale fields such as fields.nt_experiences and fields.nt_variants. See Locale handling in the Optimization SDK Suite for the broader locale model and Entry personalization and variant resolution for the entry contract.

Prerequisites

• Node.js >= 20.19.0 (24.15.0 recommended to match .nvmrc)
• pnpm

Setup

Run all steps from the monorepo root.

1. Install pnpm packages:

   pnpm install
   Copy

2. Build the local package tarballs consumed by implementations:

   pnpm build:pkgs
   Copy

3. Install this implementation so its local @contentful/* dependencies resolve from pkgs/:

   pnpm implementation:run -- node-sdk+web-sdk implementation:install
   Copy

4. Create the local .env file if it does not already exist:

   test -f implementations/node-sdk+web-sdk/.env || cp implementations/node-sdk+web-sdk/.env.example implementations/node-sdk+web-sdk/.env
   Copy

   The .env.example values are valid only against the mock server implementation. To test the implementation against a live server environment, see the mocks package for information on how to set up Contentful space with test data.

Running locally

Run these commands from the monorepo root.

1. Start servers:

   pnpm implementation:run -- node-sdk+web-sdk serve
   Copy

2. Stop servers:

   pnpm implementation:run -- node-sdk+web-sdk serve:stop
   Copy

3. Run E2E:

   pnpm test:e2e:node-sdk+web-sdk
   Copy

The application can be accessed via Web browser at http://localhost:3000. See implementations/node-sdk+web-sdk/package.json for lower-level local commands.

Running E2E tests

E2E tests are run using Playwright.

1. Install implementation dependencies, browser binaries, and system dependencies:

   pnpm setup:e2e:node-sdk+web-sdk
   Copy

2. Run the E2E test suite:

   pnpm test:e2e:node-sdk+web-sdk
   Copy

   The tests can alternatively be run using Playwright's GUI:

   pnpm implementation:run -- node-sdk+web-sdk test:e2e:ui
   Copy

Related

• @contentful/optimization-node - Node SDK package
• @contentful/optimization-web - Web SDK package
• Node SDK reference implementation - Server-only reference implementation
• Web SDK Vanilla JS reference implementation - Browser-only reference implementation
• Mocks package - Shared mock API server and fixtures