Installation

The plugin runs inside an existing Payload 3 app on the Next.js App Router, with Postgres as the database.

npm i @delmaredigital/payload-experiments@rc pg @payloadcms/db-postgres @delmaredigital/payload-puck @puckeditor/core

To pin the exact version instead:

npm i @delmaredigital/payload-experiments@0.4.0-rc.3

The quick start uses Puck and pg directly, so the first command includes them. For TypeScript, install the Postgres types too:

npm i -D @types/pg

The statistics engine, @delmaredigital/experiments-stats, is installed as a dependency of the plugin.

RequirementsCopy Anchor Link

• Node.js >=22.23.4.
• Next.js App Router. The plugin uses proxy.ts, Server Components and after().
• Postgres through @payloadcms/db-postgres, with transactions enabled. Other database adapters are not supported: deduplication, locks and aggregation use SQL that Payload's Local API cannot express.

Peer dependenciesCopy Anchor Link

Install the peers your app uses:

Puck is optional. If you use the Puck integration, it works with @delmaredigital/payload-puck >=0.10.3.

EnvironmentCopy Anchor Link

Keep your Payload secret and database connection, and add secrets for experiment signing and your results route:

PAYLOAD_SECRET=replace-with-a-random-secret-at-least-32-characters
DATABASE_URI=postgresql://postgres:postgres@localhost:5432/my-app
XP_SECRET=replace-with-a-separate-random-private-value
CRON_SECRET=replace-with-another-random-private-value

XP_SECRET signs the visitor cookie, the assignment and request headers, and preview tokens. Keep it the same across deployments and instances. Replacing it without retaining the old secret gives every visitor who has given consent a new visitor identity on their next visit; visitors without consent receive no visitor identity. To rotate it while preserving identities, pass an array with the newest secret first (see Runtimes).

Entry pointsCopy Anchor Link

The package has separate entry points so the proxy stays free of Payload, React and Puck:

The full list is in Entry points.

Next stepCopy Anchor Link

Follow the Quick start to wire the runtimes, the plugin, the proxy and a results route.