Skip to Content
Delmare Digital

Upgrading

Breaking changes and migration steps between payload-experiments release candidates.

The plugin is pre-1.0, so a minor release can require changes in your app. After every upgrade, run the migration and import-map commands, then work through the notes for each version you cross.

pnpm exec payload migrate:create
pnpm exec payload migrate
pnpm exec payload generate:importmap

Review the generated migration before applying it. The full history is in the CHANGELOG.

To 0.4

Migrate four nullable columns

xp_experiments.page_collection and its version column _xp_experiments_v.version_page_collection, xp_phases.placement_docs and xp_state.retired_slugs. No backfill is needed. If you adopt the Experiment block for a blocks field, the migration also adds the block and slots tables, their version tables and the slot enum types. If you adopt xpGoalField(), each table using it (and its version table) gains one nullable text column for xpGoal.

Fix registrations the plugin now refuses at startup

  • A registered blocks field must include the Experiment block and be top-level (inside rows, collapsibles or unnamed tabs only).
  • metricSources ids may not start with click:.

Expect new save and start refusals

  • Saves on every registered pages, blocks and puck collection can be refused with page-busy (retry) or interacting-tests (finish the other test first).
  • Start refuses placement-unpublished for Experiment blocks and Puck slots found only on drafts: publish the page first.
  • Deciding a stopped page test refuses page-target-unpublished when the Original or winner page is unpublished.
  • Publishing content that names an undefined click goal is refused for managers.

Update TypeScript

  • admin.editorUrl now receives a required editor argument ('puck' | 'blocks' | 'page') and an optional doc.
  • Snapshot.health and SummaryResponse.health are unions; narrow a row before reading .path.
  • ReadinessCode and RefusalCode gain goal-in-some-versions and placement-unchecked (and placement-removed in rc.2).
  • Add-metric responses always include warnings.

Optional: adopt the Puck integration objects

Replace hand-wired Puck pieces with experimentsPuck() and experimentsPuckEditor() through payload-puck >=0.10.3's integrations. See Puck.

To 0.3

  • linkIdentity requires verified: boolean and returns 'linked' | 'verified' | 'skipped' | 'failed'. Pass true only from a request that proves account ownership in this browser.
  • Migrate the nullable xp_identities.verified_at column and user_id index, plus decision_pages_released_at and decision_pages_released_by on xp_experiments and their version_ counterparts on _xp_experiments_v.
  • Existing identity links become unverified, which only narrows crediting. To keep the old behaviour for old rows, an optional backfill is UPDATE xp_identities SET verified_at = linked_at WHERE verified_at IS NULL;.
  • An unknown pages.collections slug now throws at startup; register host page collections before this plugin.
  • The Tests nav moved to /admin/rsc#TestsNavLinkServer; regenerate the import map. A host nav group must not also be called "Tests".

To 0.2

  • Regenerate the import map: the Tests surface is registered through the import map, and without it the Tests routes show a "not installed" message.
  • ExperimentsRootView, CollectionListRedirect and CollectionEditRedirect moved from /rsc to /admin/rsc.
  • /admin/client no longer exports the old edit-form components (StatusCell, SummaryCell, ExperimentActions, LockedFieldNotice, FlagPointSelect, ArmsField, AllocationField, TargetingAttributeField, TargetingOpField, TargetingValueField, ReviewPanel, PhaseHistory, ResultsView).
  • Prereleases publish under the npm rc dist-tag. Install with @rc or an exact version.
Edit this page on GitHub

Known limitations

What payload-experiments does not do yet, and constraints to plan around in the current release candidate.

On this page

To 0.4Migrate four nullable columnsFix registrations the plugin now refuses at startupExpect new save and start refusalsUpdate TypeScriptOptional: adopt the Puck integration objectsTo 0.3To 0.2