Contentful Personalization & Analytics

Web SDK Vanilla JS Reference Implementation

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

What this demonstrates

Use this implementation when you need the smallest browser example for the Web SDK without a framework layer. It demonstrates a static HTML integration, Web Components entry rendering, local mock API usage, Web SDK asset copying, and Playwright coverage for browser-side optimization, tracking, live updates, consent gating, and offline recovery behavior.

CDA locale handling

The static app uses en-US as its application locale for both the Web SDK top-level locale and Contentful CDA getEntry() calls. Do not use withAllLocales or 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.

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 -- web-sdk implementation:install
   Copy

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

   test -f implementations/web-sdk/.env || cp implementations/web-sdk/.env.example implementations/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 -- web-sdk serve
   Copy

2. Stop servers:

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

3. Run E2E:

   pnpm test:e2e:web-sdk
   Copy

The application can be accessed via Web browser at http://localhost:3000. See implementations/web-sdk/package.json for lower-level local commands. The local server is a lightweight Node.js HTTP server that reads .env or .env.example, injects those values into the HTML, and serves public/; PM2 manages the serve and serve:stop processes.

Running E2E tests

E2E tests are run using Playwright.

1. Install implementation dependencies:

   pnpm setup:e2e:web-sdk
   Copy

2. Install the shared Playwright browser binaries and system dependencies used by lib/e2e-web:

   pnpm --dir lib/e2e-web setup:e2e
   Copy

3. Run the E2E test suite:

   pnpm test:e2e:web-sdk
   Copy

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

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

Related

• @contentful/optimization-web - Web SDK package
• Web SDK React Adapter reference implementation - Adapter-based React reference implementation built on the Web SDK
• Mocks package - Shared mock API server and fixtures