payload-seed

@pro-laico/payload-seed is an automatic, type-safe helper for writing seed values for your collections, globals, and more. It rides the same payload generate:types you already run, so the typing stays accurate and up to date on its own, which means you and your AI tools get real feedback while writing seed content, instead of guessing at shapes. It also handles relationships and assets for you, so you never have to worry about upload order or ending up with empty references.

It also ties into the other Pro Laico plugins, so uploading assets (and working with those plugins in general) just falls into place.

Think of it as a bootstrap tool. It's for the initial data a site ships with: the content you'd otherwise hand-enter once to stand a project up, or that you let an AI scaffold for you. Running the seed uploads that content into your real storage and database, so it ends up where it belongs (your DB, S3, Mux, and so on) instead of living in your repo. It's not meant for incremental, day-to-day content changes.

pnpm add @pro-laico/payload-seed

What's included

Everything you need to seed Payload CMS as easily as possible.

• Typed seed helper functions: payload-seed automatically generates types for the collections and globals you use. With one of this package's helper functions, you can write type-safe seed data for anything.
• Relationship handling: You don't have to deal with empty references in your seeded docs anymore. payload-seed handles reference seed order automatically.
• Asset handling: Dedicated asset upload handlers can be attached to payload-seed from other plugins, on top of a standard Payload upload handler built into our type-safe helper functions.
• Seed anywhere: Seed locally via the CLI, by pinging the seed endpoint, or with the included seed button right in your Payload admin dashboard.

Quickstart

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

export default buildConfig({
  plugins: [
    seedPlugin({
      definitions: [],
      adminButton: true,
    }),
  ],
  // ...
})

// src/collections/Media/seed.ts
import { defineSeed } from '@pro-laico/payload-seed'

export default defineSeed('media', ({ file }) => [
  {
    _key: 'serviceImg',
    _file: file('service-a.jpg'), // assets/media/service-a.jpg
    alt: 'Consulting',
  },
])

// src/collections/Services/seed.ts
import { defineSeed } from '@pro-laico/payload-seed'

export default defineSeed('services', () => [
  {
    _key: 'consulting',
    title: 'Consulting',
  },
])

// src/collections/Posts/seed.ts
import { defineSeed } from '@pro-laico/payload-seed'

export default defineSeed('posts', ({ ref }) => [
  {
    _key: 'launch',
    title: 'We launched',
    heroImage: ref('media', 'serviceImg'),
    relatedService: ref('services', 'consulting'),
  },
])

import { buildConfig } from 'payload'
import { seedPlugin } from '@pro-laico/payload-seed'
import media from './collections/Media/seed'
import services from './collections/Services/seed'
import posts from './collections/Posts/seed'

export default buildConfig({
  plugins: [
    seedPlugin({
      definitions: [media, services, posts],
      adminButton: true,
    }),
  ],
  // ...
})

ENABLE_SEED=true pnpm payload seed   # CLI (Local API)
# or set ENABLE_SEED=true in your env, then:
#   click "Seed your database" in the admin header
#   or POST /api/seed  (any authenticated user)

Plugin options

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

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

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

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

defineSeed

Declares the seed data for one collection or global, one export default per seed.ts file. It infers which from the slug: a collection slug means the builder returns an array of records; a global slug means it returns a single data object (no _key). Returns a seed definition you add to seedPlugin({ definitions }).

The Reference tab lists the parameters; TypeScript is a minimal example.

// src/collections/Services/seed.ts
import { defineSeed } from '@pro-laico/payload-seed'

// slug + a builder returning the data (an array of records for a collection).
export default defineSeed('services', () => [
  {
    _key: 'consulting',
    title: 'Consulting',
  },
])

Collections

Each record is the collection's own data plus a required _key (a local handle other seed files target with ref(slug, key)) and, for upload / provider collections, an optional _file carrying its source file. Point relationship fields at other records with ref(); attach a file with file() on _file:

// src/collections/Media/seed.ts: each doc carries its file on `_file`
import { defineSeed } from '@pro-laico/payload-seed'

export default defineSeed('media', ({ file }) => [
  {
    _key: 'serviceImg',
    _file: file('service-a.jpg'), // assets/media/service-a.jpg
    alt: 'Consulting',
  },
])

// src/collections/Posts/seed.ts: point at other seeded docs by ref
import { defineSeed } from '@pro-laico/payload-seed'

export default defineSeed('posts', ({ ref }) => [
  {
    _key: 'launch',
    title: 'We launched',
    heroImage: ref('media', 'serviceImg'),          // upload-field relationship, resolved by ref
    relatedService: ref('services', 'consulting'),  // typed dependency edge across files
  },
])

Records are typed against your generated Payload types (RequiredDataFromCollectionSlug<slug>), with relationship fields widened to also accept ref() tokens. Change a collection's fields and the seed file shows a TS error until it matches; unknown fields are rejected too. The producing side (_key) stays a free string; only the consuming side (ref) is checked.

Globals

Pass a global slug and the builder returns a single data object instead of an array (a global is a singleton, so there's no _key). It gets the same tokens, and globals are updated after all their dependencies exist:

// src/globals/SiteSettings/seed.ts
import { defineSeed } from '@pro-laico/payload-seed'

export default defineSeed('site-settings', ({ ref }) => ({
  /* SiteSettings data; ref('services', 'consulting') etc. */
}))

Tokens

Inside a build callback you get two tokens. The engine resolves them at create time, and ref doubles as the dependency edge that orders the run.

You never import either; they're handed to every build callback (({ ref, file }) => …), so they can't drift from the data they point at. file goes on the record's _file meta-key; everything else is an ordinary field.

Run payload generate:types and every ref() is checked against your real _keys: rename or remove a seeded item and each stale reference becomes a TS error (unknown collections error too). See How it works for the mechanism.

Files (_file)

An asset is just a seeded doc that carries a file. Put it on the record's _file meta-key with the file() token. How the file is delivered depends on the doc's collection. The engine decides, you don't:

• An upload collection (e.g. media, images, icon) → the bytes are read and uploaded as the doc's file.
• A custom.seedAsset collection (e.g. Mux) → the resolved path + options are handed to the collection's own ingest hook (see Custom ingestion).

// src/collections/Media/seed.ts
import { defineSeed } from '@pro-laico/payload-seed'

export default defineSeed('media', ({ file }) => [
  {
    _key: 'hero',
    _file: file('hero.jpg'), // assets/media/hero.jpg
    alt: 'Hero',
    focalX: 78,
    focalY: 32,
  },
])

file(name, options?): name is the source filename (resolved below); options is an optional bag merged into a custom.seedAsset collection's ingest source field (e.g. a Mux playbackPolicy) and ignored for native uploads. The doc's own fields (alt, focal point, title, …) are ordinary record fields, typed against the collection, so an upload collection that requires alt makes the seed record require it too. Focal points set the upload's focal point, so seeded images crop to the right subject the moment they're served (e.g. by @pro-laico/payload-images).

Where files live

Every _file resolves to the same three-part path — the assets dir, a per-collection folder, then the name you pass:

<assetsDir> / <collection folder> / <file name>
assets      / media              / hero.jpg

The folder is the collection slug, so this needs no config. On disk:

root/
  assets/                  ← assetsDir        (default 'assets', relative to project root)
    media/                 ← collection folder (the slug; rename via assetSubDirs)
      hero.jpg             ← file('hero.jpg')
      portraits/           ← a subpath in the name nests further
        jane.jpg           ← file('portraits/jane.jpg')

The defineSeed using those files:

// src/collections/Media/seed.ts
export default defineSeed('media', ({ file }) => [
  {
    _key: 'hero',
    _file: file('hero.jpg'), // assets/media/hero.jpg
    alt: 'Hero',
  },
  {
    _key: 'jane',
    _file: file('portraits/jane.jpg'), // assets/media/portraits/jane.jpg
    alt: 'Jane',
  },
])

A _file can also be an absolute path (file('/tmp/logo.svg')), used as-is for a file outside the tree.

Custom ingestion

Most collections take a plain Payload upload for their _file and seed natively. A few ingest their file through their own hook instead — e.g. @pro-laico/payload-mux's mux-video, whose bytes go to Mux. Mark such a collection's own config and the engine hands the _file to that hook (via a sourceField) rather than uploading bytes:

// the collection's own config — usually set by its plugin, not by you
{
  slug: 'mux-video',
  custom: {
    seedAsset: { sourceField: 'source' }, // or `seedAsset: true` for the defaults
  },
  fields: [
    // the field the engine writes `{ file, ...options }` to, read by the ingest hook
    { name: 'source', type: 'json', admin: { hidden: true } },
    // ...the rest of the collection
  ],
}

The engine auto-discovers the marker from the live config — nothing to register, and the owning plugin never imports payload-seed. The doc then seeds like any other (_file + ref()). Collections whose asset is a plain upload (payload-fonts' fontOriginal, payload-images' image) need no marker. See payload-mux → Seeding for a worked example.

Disabled seeds

Some collections can't always seed — @pro-laico/payload-mux's mux-video needs API credentials to ingest a clip. Don't gate the definition on the environment (that shifts the generated seed-ref types with it); the collection declares it instead:

// set by the owning plugin when it can't ingest — e.g. payload-mux without MUX_* env vars
{
  slug: 'mux-video',
  custom: { seedDisabled: 'Mux credentials not set (MUX_TOKEN_ID / MUX_TOKEN_SECRET)' },
}

The engine skips that definition (warning with the reason) and drops any optional field whose ref() points at it — a required ref is a hard error. The definition stays registered, so types don't change with the environment; set the env vars and the next run seeds it and fills the dropped refs back in. To gate a definition yourself, defineSeed takes the same flag directly: defineSeed('reports', build, { disabled: !process.env.REPORTS_API_KEY }).

Running the seed

Four entry points run the same engine over the same definitions — pick by 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 — leave it unset in production. The fourth, seed(), is the in-code path and is deliberately not gated (that's what lets a test drive it). Every entry point is destructive — it clears the seeded collections before recreating them — so run it on purpose. (See Quickstart for setting ENABLE_SEED.)

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

# 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": [ … ] }

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

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

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)

How it works

Every entry point runs the same engine. You don't need any of this to write seeds; it's here for when you're debugging or curious.

What a seed run does

Trigger a seed from any entry point and the engine runs the same fixed sequence — starting from your in-memory defineSeed output and ending with a fully-populated database:

How typed refs are generated

The plugin injects a SeedRegistry into payload-types.ts via Payload's own typescript.postProcess hook, riding the same generate:types command you already run. That makes the augmentation global with no import, exactly like Payload's generated GeneratedTypes, so ref('services', 'consulting') is checked against your real _keys. Without codegen, refs fall back to runtime validation: safe either way, fully safe with it.

Disable revalidation

The engine sets context: { disableRevalidate: true } on every create, update, and delete. Have your afterChange / afterDelete revalidation hooks check for it and skip, so a bulk seed doesn't fire a revalidation per doc:

export const revalidatePost: CollectionAfterChangeHook = ({ doc, context }) => {
  if (!context.disableRevalidate) revalidatePath(`/posts/${doc.slug}`)
  return doc
}

Gotchas

A few things to keep in mind:

• Every run is destructive. A seed clears each collection it touches before recreating it — a reset, not an append. Re-running wipes and rebuilds, so never point it at data you want to keep.
• Nothing runs without ENABLE_SEED. The admin button, endpoint, and CLI all no-op (403) unless ENABLE_SEED is exactly "true". The in-code seed() is the exception — it skips the gate, so it will wipe whatever database it's handed. Guard your script / test setup accordingly.
• Circular references need an optional field. Two docs that reference each other are fine — the engine breaks the cycle by deferring one side's ref and setting it in a second pass once both docs exist. That field just has to be optional (it's created null first). A cycle where every ref sits on a required field is a hard error naming it (posts:a -> authors:b -> posts:a) — make one side optional to break it.
• A missing source file only warns. If a _file isn't found under <assetsDir>/<subdir>/, the engine logs _file '…' not found and keeps going — the doc is still created (and an upload collection that requires a file may then error downstream). Watch the logs for typos. The subdir defaults to the collection slug; override it with assetSubDirs.
• Don't env-gate a definition out of the array. Conditionally registering a definition (...(withMux ? [videos] : [])) makes the generated seed-ref types depend on the environment — the dev server regenerates them on boot and every ref() at it flips between valid and error. Register it unconditionally and let it be skipped at runtime instead (custom.seedDisabled, or defineSeed's disabled).
• Typed refs need generate:types. ref() keys are only checked once the SeedRegistry is generated; before that they fall back to runtime validation. Rename a _key and you must regenerate types for the compile-time check to catch stale references.
• Globals can't be referenced, and update last. ref() points at collection docs only — a global can reference docs, but a doc can't reference a global. Globals are applied after every doc exists.
• CLI dies with ENOENT … node:crypto?tsx-namespace=… on Node 24? That's tsx, not the seed. Payload's CLI loads bin scripts through tsx's tsImport(), and tsx ≥ 4.21.1 mis-resolves a dependency's bare require('crypto') under Node 24's module hooks — killing any custom payload <script> at boot. Pin tsx below the regression until it's fixed upstream (pnpm: overrides: { tsx: '4.19.4' }). The admin button and POST /api/seed are unaffected.

Exports