Seed Payload CMS safely

A Payload CMS seed script creates known documents through the Local API so a new database, preview environment, or local project starts with useful content. The safest scripts are explicit about what they own, refuse ambiguous matches, and can be run twice without creating duplicates.

This guide shows both sides of that job:

• a small project-owned TypeScript seed for a collection you control;
• the generated demo seed that Payload Components can create for an installed block.

Pick the right seed path

Payload exposes the Local API for server-side collection operations. Its configuration reference also supports project-owned command scripts. Those primitives are enough to seed a project; the hard part is deciding how a rerun identifies its own records.

Write a small project-owned seed

Create a TypeScript file inside the project. This example owns one draft page by a dedicated slug, refuses duplicates, and updates the exact document ID returned by the lookup.

import { getPayload } from 'payload'

import config from '@payload-config'

const payload = await getPayload({ config })
const seedSlug = 'example-seeded-page'

const matches = await payload.find({
  collection: 'pages',
  depth: 0,
  draft: true,
  limit: 2,
  overrideAccess: true,
  where: {
    slug: {
      equals: seedSlug,
    },
  },
})

if (matches.docs.length > 1) {
  throw new Error(`Refusing to seed: more than one Page uses ${seedSlug}`)
}

const data = {
  title: 'Example seeded page',
  slug: seedSlug,
  layout: [],
  _status: 'draft' as const,
}

if (matches.docs[0]) {
  await payload.update({
    collection: 'pages',
    id: matches.docs[0].id,
    data,
    draft: true,
    overrideAccess: true,
    overrideLock: false,
  })
} else {
  await payload.create({
    collection: 'pages',
    data,
    draft: true,
    overrideAccess: true,
  })
}

console.log(`Seeded draft Page: ${seedSlug}`)

Run the script from the project root:

pnpm exec payload run src/seed.ts

Use the equivalent package-manager command if the project does not use pnpm. Keep the script in version control so the team can review changes to its write behavior.

Make reruns predictable

The example above is intentionally small. Before using the same pattern for a larger seed, decide four things.

If a create can be interrupted after the database commit but before local state is saved, a slug alone is not enough for recovery. Record a unique operation token before the create, write it into the new document, and save the returned ID afterward. A retry can then adopt only the single document carrying that exact token.

For multi-document seeds, keep a private state file that records every created ID. Validate the file before mutations, write state atomically, and stop when the database and local record disagree. This is more work than a short lookup, but it prevents a retry from claiming content it did not create.

Generate a Payload Components demo seed

Payload Components packages that stricter ownership behavior for installable blocks. Add --demo to a normal component install:

The install writes the block source, registers it in the Pages layout and RenderBlocks, regenerates types and the admin import map, records install state, and then creates this operator-run script:

The CLI does not connect to the database. Review the generated file, select the intended environment, and run it yourself:

pnpm exec payload run payload-components/seed-hero-basic.ts

If hero-basic is already installed, generate the same script without rerunning the installer:

npx payload-components seed hero-basic
pnpm exec payload run payload-components/seed-hero-basic.ts

The standalone seed command checks the recorded install, component files, dependencies, Pages registration, renderer mapping, manifest, and registry dependencies before it writes anything. If those checks do not describe a complete current install, it exits non-zero and leaves the seed path unchanged. Repair the install with npx payload-components add hero-basic, then retry.

What the generated demo owns

The generated script uses a narrow contract rather than a generic same-slug update.

For hero-basic, the generated Page uses:

• slug payload-components-demo-hero-basic;
• title Payload Components demo — Hero Basic;
• a block marker beginning payload-components:demo:hero-basic;
• _status: 'draft', so publishing remains an explicit editor action.

The script requires the pages collection to have drafts enabled. It checks that requirement before it queries or mutates content. On a rerun, it updates only the exact Page ID in the private ownership file after the database record still matches the expected token, slug, title, and block shape.

For a component with required uploads, the script can create one marked placeholder Media record and save its ID immediately. It never deletes Media. Temporary placeholder files live in a unique operating-system directory and are removed after the upload attempt.

Review access and lock behavior

The generated operator-run script uses overrideAccess: true. That is deliberate: a seed command runs outside a normal signed-in request and must be able to create the fixture it describes. It is also why you should inspect the target environment and the generated file before running it.

Owned Page updates use overrideLock: false. If another editor holds a lock, the seed does not silently bypass it. All Pages are written as drafts, so you can inspect the block fields in the admin panel before publishing.

These boundaries are separate from installation. The wrapper CLI owns files and Payload wiring; the generated script owns the database work. See how the runtimes stay separate for the full architecture boundary.

Common seed failures

Before you run any seed

• Confirm the database and environment variables belong to the intended local, preview, or production environment.
• Review every collection the script can create or update.
• Verify that lookup keys are unique and ambiguous results cause a hard failure.
• Prefer draft documents when the collection supports editorial review.
• Back up valuable data and know how to restore it.
• Run once, inspect the created IDs and fields, then run again to prove the result does not duplicate.

To install a component before generating its demo, start with the Payload Components installation guide. To understand every file and collection change made by the installer, follow the first block walkthrough.