# Reference

URL: /docs/plugins/payload-seed/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.

**Reference**

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `enabled` | `boolean` | `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). |
| `definitions` | `SeedDefinition[]` |  | 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. |
| `options` | `SeedOptions` |  | The plugin's own knobs. |
| `options.assetsDir` | `string` | `'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. |
| `options.assetSubDirs` | `Partial<Record<CollectionSlug, string>>` | `{}` | 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' }. |

**TypeScript**

```ts
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](/docs/plugins/payload-seed/running). |

## 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](/docs/plugins/payload-seed/running)).                                                                                                 |
| `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](/docs/plugins/payload-seed/writing-seeds).

## Next

- [Writing seeds](/docs/plugins/payload-seed/writing-seeds) — `defineSeed`, records, `_key`, globals, tokens, and where files live.
- [Running the seed](/docs/plugins/payload-seed/running) — the four entry points and response shapes.
- [Advanced](/docs/plugins/payload-seed/advanced) — custom ingestion, disabled seeds, and disabling revalidation.
- [Troubleshooting](/docs/plugins/payload-seed/troubleshooting) — symptom-first fixes.