Payload Version Backfill Plugin

payload-plugin-version-backfill backfills a baseline version for existing documents when a Payload collection has versioning enabled without drafts.

This fixes the migration case where a collection already contains content, then later enables:

versions: {
  drafts: false,
  maxPerDoc: 20,
}

Without a baseline version, the first update can feel like a brand-new versioned document instead of a change from the original content. This plugin seeds that missing first version once, then lets normal Payload versioning take over.

What It Does

• Runs on startup through config.onInit
• Waits for any existing onInit logic to finish first
• Only processes the collections you explicitly configure
• Only backfills documents that currently have zero versions
• Leaves Payload's version storage behavior unchanged

Payload versions are still full document snapshots. This plugin only ensures pre-existing documents receive their missing initial snapshot.

Installation

pnpm add payload-plugin-version-backfill

Usage

import { buildConfig } from 'payload'
import { versionsBackfillPlugin } from 'payload-plugin-version-backfill'

import { Pages } from './collections/Pages'
import { Posts } from './collections/Posts'

export default buildConfig({
  collections: [Pages, Posts],
  plugins: [
    versionsBackfillPlugin({
      collections: [Posts, Pages],
      batchSize: 100,
    }),
  ],
})

Options

versionsBackfillPlugin({
  collections: [Posts, Pages],
  batchSize: 100,
})

• collections: Required list of collection configs or slugs to backfill
• batchSize: Optional pagination size, defaults to 100

Behavior Notes

• Collections are skipped if they do not exist
• Collections are skipped if versioning is disabled
• Collections are skipped if drafts are enabled
• versions: true is treated as eligible
• versions: { drafts: false } is treated as eligible
• Documents that already have at least one version are skipped

Once the baseline versions exist, future updates are handled by Payload's built-in versioning behavior.