Skip to content

README.md

Latest commit

 

History

History
140 lines (97 loc) · 4.38 KB

README.md

File metadata and controls

140 lines (97 loc) · 4.38 KB

Contentful Logo

Contentful Personalization & Analytics

Node SSR Only Reference Implementation

Warning

The Optimization SDK Suite is pre-release (alpha). Breaking changes can be published at any time.

This is a reference implementation for the Optimization Node SDK and is part of the Contentful Optimization SDK Suite.

The server creates one stateless Node SDK instance at module load and passes request-specific options directly to stateless event methods inside each incoming request handler. Because the application explicitly decides when to call the Node SDK, emitted Node events use the SDK's default consented event label.

Warning

Cache only raw Contentful entries in SSR flows. Do not mutate shared cached entries during request rendering, and do not share merge-tag-rendered output across users.

CDA locale handling

This app defines one APP_LOCALE, passes it to forRequest({ locale: APP_LOCALE }), uses it in event context, and passes it directly to Contentful CDA fetches. Raw entry cache keys include the application locale so request-specific entry data cannot drift. Do not use contentful.js withAllLocales or raw CDA locale=*; SDK entry resolution 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.

What this demonstrates

Use this implementation when you need a minimal server-rendered example for @contentful/optimization-node. It demonstrates request-scoped Experience API options, SSR-safe entry resolution, merge-tag rendering, profile-aware event calls, and local mock API usage.

Prerequisites

  • Node.js >= 20.19.0 (24.13.0 recommended to match .nvmrc)
  • pnpm 10.x

Setup

Run all steps from the monorepo root.

  1. Install pnpm packages:

    pnpm install

  2. Build the local package tarballs consumed by implementations:

    pnpm build:pkgs

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

    pnpm implementation:run -- node-sdk implementation:install

  4. Configure the environment in a .env file in implementations/node-sdk based on the .env.example included file. The file is pre-populated with values that 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 serve

  2. Stop servers:

    pnpm implementation:run -- node-sdk serve:stop

  3. Run E2E:

    pnpm test:e2e:node-sdk

The application can be accessed via Web browser at http://localhost:3000. See implementations/node-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

  2. Run the E2E test suite:

    pnpm test:e2e:node-sdk

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

    pnpm implementation:run -- node-sdk test:e2e:ui

Related