Payload Scripts

This page explains the scripts available in frontend/payload/src/scripts, what each one does, and how to run it. A package command such as pnpm seed:master starts the full entry-point script configured for that command. Helper files such as seedMaster.ts are called by other scripts and are not separate commands.

Before Running a Script

Run commands from the Payload project directory:

cd frontend/payload

Install dependencies if this is a fresh checkout, then start the Payload service in a separate terminal when running scripts that call the HTTP API:

pnpm install
pnpm dev

Most seed and alert scripts read these variables from the local .env file:

Variable	Purpose
`TARGET_API_URL`	Payload API base URL. Defaults to `http://localhost:3000/api`. Check this value before running a script so it does not target a shared or production environment by mistake.
`SEED_ADMIN_EMAIL`	Admin account used by seed and alert scripts to sign in.
`SEED_ADMIN_PASSWORD`	Password for that admin account.
`ALERT_TEST_USER_EMAIL`	Optional target user for the saved-search alert test. It can instead be passed as a command-line argument.

The repository’s .env.example does not currently list the seed-specific variables. Add them to your local .env as needed; never put real credentials in documentation or commit them. Seed scripts generally create records rather than replacing existing data, so repeated runs can add duplicate listings or media.

Seed and Alert Commands

Run these package commands from frontend/payload:

Command	What it runs	Notes
`pnpm seed:master`	`src/scripts/seed-master.ts`	Adds default locations, amenities, property types, and listing categories. It checks for existing names before creating most records. Requires a working API and admin credentials.
`pnpm seed:providing`	`src/scripts/seed.ts`	Creates a sample providing hierarchy: homes, rooms, and beds. Requires master data and images in `src/scripts/assets/homes`, `rooms`, and `beds`. Run `pnpm seed:master` first if master data is missing.
`pnpm seed:seeking`	`src/scripts/seed-seeking.ts`	Creates 10 random seeking listings. Requires master locations and listing categories.
`pnpm seed:nid`	`src/scripts/seed-nid.ts`	Downloads sample images and attempts to create three NID test accounts and verification records. Requires outbound access to `picsum.photos`, a working API, and admin credentials. The current image-collection and existing-user ID issues described below can cause the NID seed to fail; treat it as unverified.
`pnpm test:alert [email protected]`	`src/scripts/test-saved-search-alert.ts`	Creates a saved search for the target account and a matching home listing, then exercises the notification/email hook. Requires admin credentials, a target user, master data, and working email configuration or development email logging. It also uploads sample images and leaves the created test records in the database.

For the alert test, the target email can also be set with ALERT_TEST_USER_EMAIL and the command run as pnpm test:alert. See the Saved Searches documentation for more detail about the alert flow.

Running the Combined Seed

The combined entry point runs master data, providing listings, seeking listings, and NID verification seed data in sequence. It does not have a package.json alias, so run it directly with tsx:

pnpm exec tsx src/scripts/seed-all.ts

This command requires the same API and admin credentials as the individual seed scripts. It also requires local image folders under src/scripts/assets for homes, rooms, beds, and NID samples. The helper modules seedMaster.ts, seedProviding.ts, seedSeeking.ts, and seedNID.ts are invoked by this combined entry point; they are not configured as individual pnpm commands.

The NID seeding code currently needs attention before relying on it: both the standalone seed-nid.ts and the combined seed’s seedNID.ts upload through the general media collection, while NID verification records expect image relationships from nid-media. The standalone script also reads an existing user’s ID from the wrong shape of the docs array. Treat NID seeding as unverified until those mismatches are fixed; use test-only data and check the output and Admin records.

Maintenance Scripts

These scripts do not have package aliases. Run them directly from frontend/payload:

pnpm exec tsx src/scripts/cleanupOtps.ts
pnpm exec tsx src/scripts/clean.ts

Script	What it does	Important caution
`cleanupOtps.ts`	Uses the local Payload configuration to clear expired `otp_code` and `otp_expiration` values from user records.	This is a one-off cleanup, not a scheduled job. Run it with the correct database environment configured. Expired OTPs are rejected by the OTP flow even before cleanup runs.
`clean.ts`	Logs in with the seed admin credentials and deletes records from bed, room, home, and seeking listings, NID verifications, and general media.	Destructive. `TARGET_API_URL` defaults to local development; confirm it before running. It does not clean every collection and does not delete `nid-media`. The script only fetches up to 500 records per collection.

Do not run clean.ts against shared, staging, or production data unless the team has explicitly approved the cleanup and confirmed the target.

Automated Tests

The Payload package also defines these test commands:

Command	What it runs
`pnpm test:int`	Vitest integration tests.
`pnpm test:e2e`	Playwright end-to-end tests.
`pnpm test`	Runs integration tests, then end-to-end tests.

These are test suites rather than data-seeding scripts. Their environment requirements are defined by the Payload test configuration.

Script Map

File	Role
`src/scripts/seed-master.ts`	Standalone master-data seeder; package alias `seed:master`.
`src/scripts/seed.ts`	Providing-listing seeder; package alias `seed:providing`.
`src/scripts/seed-seeking.ts`	Seeking-listing seeder; package alias `seed:seeking`.
`src/scripts/seed-nid.ts`	Standalone NID seeder; package alias `seed:nid`.
`src/scripts/seed-all.ts`	Combined seed entry point; run using `pnpm exec tsx`.
`src/scripts/seedMaster.ts`, `seedProviding.ts`, `seedSeeking.ts`, `seedNID.ts`	Helper modules used by `seed-all.ts`.
`src/scripts/test-saved-search-alert.ts`	Saved-search notification test; package alias `test:alert`.
`src/scripts/cleanupOtps.ts`, `clean.ts`	One-off cleanup scripts; run using `pnpm exec tsx`.