Reference

Plugin options, environment variables, CLI commands, endpoints, and exports for payload-seed.

Plugin options

seedPlugin(options?) is the single entry point. One call registers the payload seed command, the POST /api/seed endpoint, the admin button, and the type augmentation that checks your refs. It does nothing useful without definitions.

The admin button is always registered. It is double-guarded already — the button renders null and POST /api/seed 403s unless ENABLE_SEED=true, so ENABLE_SEED is the real switch. Because the button is wired by string path, regenerate the admin import map with pnpm payload generate:importmap after adding the plugin.

The Reference tab is the interactive view; TypeScript is the same shape in code, every option at its default.

enabledbooleandefault true

When false, the plugin registers nothing: no command, endpoint, button, or type augmentation. This is a build-time switch — to turn seeding itself off at runtime, leave ENABLE_SEED unset (it already is by default).

definitionsSeedDefinition[]

The seed definitions: your defineSeed exports. The same array feeds the seed run and the typed SeedRegistry injected into payload-types.ts. Omit it and the seed runs but warns there is nothing to do. Kept at the root — it's what the plugin is.

optionsSeedOptions

The plugin's own knobs.

assetsDirstringdefault 'assets'

The assets root where _file source files live, relative to the project root. A native upload's file is looked up under its per-collection subdir (see assetSubDirs) then the root; providers look under their own subdir.

assetSubDirsPartial<Record<CollectionSlug, string>>default {}

Per-collection subdirectory (under assetsDir) for a collection's _file source files. Defaults to the collection slug (media resolves under assets/media/), so a folder named after the collection just works. Set an entry to use a different folder name, e.g. { media: 'images' } or { fontOriginal: 'font' }.

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

// Every option at its default.
seedPlugin({
  enabled: true,
  // definitions: [media, services, posts], // no default; your seed.ts exports
  options: {
    assetsDir: 'assets',
    assetSubDirs: {}, // default folder per collection is its slug; override here, e.g. { media: 'images' }
  },
})

Environment variables

Variable	Default	What
`ENABLE_SEED`	unset	Must equal `"true"` to run the endpoint, CLI, or admin button. Off by default; never set it in production.

CLI commands

Command	What
`payload seed`	Run the seed over the Local API. Gated by `ENABLE_SEED=true`.

Endpoints

Route	What
`POST /api/seed`	Run the seed over HTTP. Gated by `ENABLE_SEED=true`. See Running the seed.

Exports

Export	From	What
`seedPlugin`	`@pro-laico/payload-seed`	The plugin factory.
`SeedPluginOptions`	`@pro-laico/payload-seed`	The `seedPlugin()` / `seed()` options type — `{ enabled?, definitions?, options? }`.
`readSeedMarker`	`@pro-laico/payload-seed`	`readSeedMarker(config)` returns the typed `config.custom.payloadSeed` — `{ options, endpointPath, assetsDir }` — so a script can resolve the configured paths off a live config instead of restating them.
`PayloadSeedMarker`	`@pro-laico/payload-seed`	The marker's type — the shape `readSeedMarker` returns.
`defineSeed`	`@pro-laico/payload-seed`	Declare a collection's seed records or a global's seed data (inferred from the slug; one default export per `seed.ts`).
`seed`	`@pro-laico/payload-seed`	Run the seed from a script / test / migration (see Running the seed).
`SeedResult`	`@pro-laico/payload-seed`	What `seed()` returns — `{ created, collections, globals, order, deferred, skipped }`.
`registerAfterSeedListener` / `AfterSeedListener`	`@pro-laico/payload-seed`	Register a callback (and its type) that runs after every seed, `(result, { payload, req })` — a cross-package channel a sibling plugin can hook without importing the run.
`SeedRunError` / `SeedValidationError`	`@pro-laico/payload-seed`	The error classes the engine throws — a create failure, and collected validation issues (the `400`'s `issues`).
`ref` / `file` / `isRef` / `isFileToken`	`@pro-laico/payload-seed`	The token constructors + type guards, for code that builds seed data outside a builder callback (unit tests, composed fragments). Inside a builder, use the supplied tokens.
`SeedTokens` / `WithRefs` / `CollectionSeedData` / `GlobalSeedData`	`@pro-laico/payload-seed`	Types for seed helpers composed across files: type a fragment's `{ ref, file }` parameter, widen generated data types to accept `Ref` tokens.
`Ref` / `FileToken`	`@pro-laico/payload-seed`	The token value types themselves.
`SeedRegistry`	`@pro-laico/payload-seed`	Augmentable interface `generate:types` fills in, so `ref()` keys are checked. Not imported by name.
`SeedButton`	`@pro-laico/payload-seed/components/SeedButton`	The admin Seed your database button (always registered, wired via the import map). Server component — renders nothing unless `ENABLE_SEED` is `"true"`.

Collections & globals

payload-seed registers no collections of its own — it seeds the ones you already have. Declare seed records and globals with defineSeed; see Writing seeds.

Writing seeds — defineSeed, records, _key, globals, tokens, and where files live.
Running the seed — the four entry points and response shapes.
Advanced — custom ingestion, disabled seeds, and disabling revalidation.
Troubleshooting — symptom-first fixes.