Running the seed

Four entry points run the same seed engine over the same definitions. Pick the one that fits where you are.

Three of them — the admin button, the HTTP endpoint, and the CLI — sit behind the ENABLE_SEED kill switch. If ENABLE_SEED isn't exactly "true", they refuse to run. The fourth, seed(), is the in-code path and is deliberately not gated, which is what lets a test drive the real seed.

See the Quickstart for setting ENABLE_SEED.

The four entry points

Admin button

The friendliest path: a "Seed your database" button in the admin header. The plugin registers it for you — set ENABLE_SEED=true, then click it. It POSTs to /api/seed as the logged-in user and reports success (or the error) inline.

// payload.config.ts
seedPlugin({ definitions: [media, services, posts] })

When ENABLE_SEED isn't set, the button doesn't render at all — environments where the endpoint would refuse anyway never show it.

Best for: local development and demos — the quickest way to reseed while you build.

HTTP endpoint

The plugin registers POST /api/seed — a Payload REST route, and the very route the admin button calls. Hit it from a script, a CI step, or curl against a running app. It's guarded twice; both must pass:

• ENABLE_SEED must equal "true", or it returns 403 and does nothing (the primary safety — leave it unset in production and the route is inert).
• The request must be authenticated — a Payload auth cookie or API key — or 403. Any logged-in user qualifies, so gate by environment with ENABLE_SEED, not by role.

# Send your Payload auth cookie or API key (here: an API key on the `users` collection).
curl -X POST https://your-app.com/api/seed \
  -H 'Authorization: users API-Key <your-api-key>'
# 200 → { "success": true, "created": { "media": 3, "services": 2, "posts": 1 }, "order": [ … ] }

Responses

Best for: CI/CD, or seeding a deployed environment over HTTP.

CLI

The plugin adds a payload seed command (a bin on the package) that runs over the Local API — no HTTP, no auth, just a terminal. Wire a script and run it with the switch on:

// package.json
{ "scripts": { "seed": "payload seed" } }

ENABLE_SEED=true pnpm seed
# [payload-seed] clearing collections...
# [payload-seed] seeding documents...
# [payload-seed] seed complete.

Best for: a terminal, or a pre-deploy CI step that seeds before the app serves traffic.

Programmatic

Call the engine directly with seed() — for tests, migrations, or a custom script. It builds a Local API req if you don't pass one and resolves the options you hand it. Unlike the other three it is not behind ENABLE_SEED (the gate lives on the entry points), so a test can drive the real seed:

import { seed } from '@pro-laico/payload-seed'
import { getPayload } from 'payload'
import config from '@payload-config'

const payload = await getPayload({ config })
const result = await seed({ payload, options: { definitions: [media, services, posts] } })

result.created  // → { media: 3, services: 2, posts: 1 }              (created docs per collection)
result.order    // → ['media:hero', 'services:consulting', 'posts:launch']  (topo-sorted create order)
result.deferred // → fields created null to break a ref cycle, set in the second pass
result.skipped  // → [{ slug, reason }] definitions skipped this run (disabled / custom.seedDisabled)

SeedResult fields

seed() returns { created, collections, globals, order, deferred, skipped } — the same shape the endpoint response carries (alongside success: true) and the source the CLI's completion log summarizes.

Still destructive; call it deliberately. Best for: integration tests and migrations.

Next

• Writing seeds — defineSeed, records, refs, and files.
• Advanced — custom ingestion, disabled seeds, how the engine works, and disabling revalidation.
• Troubleshooting — the node:crypto?tsx-namespace CLI bug and other failure modes.