Overview
A/B testing for Payload CMS and Next.js. Editors test blocks, pages and settings; results appear in the admin.
@delmaredigital/payload-experiments adds A/B testing to a Payload CMS and Next.js site, using the content you already manage. An editor tests a block on a page, a whole page against another page, or a setting a developer has made testable. They pick a goal, compare the Original with up to three new versions, and read the result in the Payload admin. When a version wins, they make it the permanent content.
There is no vendor. Exposures, conversions and results are stored in your own Postgres database, and the statistics run inside your app.
Prerelease
The current release is 0.4.0-rc.3, a release candidate published under npm's rc tag. The plugin is pre-1.0: a minor release can require changes in your app. Read Upgrading before you move between versions.
What it does
- Three kinds of test editors can run without code. A block on a page (Puck or a Payload blocks field), a whole page against another page at its own address, or a setting at a flag point your developer registered once. Developers can also run code tests.
- It counts people who saw the content. Being assigned to a version is not enough; an exposure is recorded only when that version is rendered, scrolled into view, or shown as a page. See Exposures.
- Goals you already have. Signups, purchases, donations or any outcome your app can report, plus click goals that editors name and attach to buttons and links. Guardrail goals check that a change does not hurt something else.
- Results you can trust while the test runs. Sequential testing keeps results valid when people check them every day. Results warn when traffic does not split as configured (sample-ratio mismatch), and the statistics are a port of GrowthBook's
gbstatschecked against it numerically. See How results are computed. - A plain-English verdict. Each results run ends in one recommendation, such as "Variant A is statistically better" or "Data problem: traffic isn't splitting as set." See Verdicts.
- Make the winner permanent. Make it the content copies the winning block into the page, keeps a winning page at the Original's address, or saves winning settings as defaults.
How the pieces fit
| Piece | Where it runs | What it does |
|---|---|---|
| Proxy runtime | Next.js proxy.ts | Gives each visitor a signed id, assigns versions, rewrites whole-page tests |
| Server runtime | Server Components, route handlers, Payload config | Reads assignments, records exposures and conversions |
| Plugin | payload.config.ts | Collections, admin screens, endpoints, content guards |
| Results route | A cron route you own | Runs runResults to compute results on a schedule |
| Client provider | Your layout or page | Viewport and pageview exposures, click goals |
Where to go next
Installation
Requirements, peers and the npm tag to install.
Quick start
Wire the plugin and run a first block test end to end.
Concepts
Test kinds, exposures, goals, holdouts and layers.
Statistics
How results are computed and why you can check them early.
Statistics engine
The statistics live in a separate package, @delmaredigital/experiments-stats, a dependency-free TypeScript port of GrowthBook's gbstats. You do not need to install it to use the plugin. See experiments-stats if you want to use it directly.
License
MIT. The statistical methods are ported from GrowthBook gbstats (MIT, © GrowthBook, Inc.).