obsidian/wiki/payloadcms/local-api-outside-nextjs.md

title	aliases	tags	sources	created	updated
Payload Local API — Outside Next.js	payload-standalone payload-scripts payload-outside-nextjs	payloadcms local-api standalone scripts esm	raw/local-api__outside-nextjs.md	2026-05-15	2026-05-15

Overview

Payload can run entirely outside of Next.js — useful for standalone scripts (seeding, migrations, one-off ops) or in other frontend frameworks (SvelteKit, Remix, Nuxt).

Requirement: Payload is fully ESM. Scripts must be ESM format or use dynamic imports.

Running Standalone Scripts

Use getPayload({ config }) to get an initialized Payload instance:

import { getPayload } from 'payload'
import config from '@payload-config'

const seed = async () => {
  const payload = await getPayload({ config })

  await payload.create({
    collection: 'users',
    data: { email: 'dev@payloadcms.com', password: 'some-password' },
  })
}

await seed()

Execute with:

payload run src/seed.ts

payload run — What It Does

1. Loads env vars exactly like Next.js does — no need for dotenv (using dotenv directly can cause env var mismatches)
2. Initializes tsx — runs TypeScript directly without manually installing ts-node/tsx

Troubleshooting Import Errors

Option 1 — SWC mode (faster, but may break some imports)

payload run src/seed.ts --use-swc

Requires @swc-node/register installed in the project.

Option 2 — Alternative runtime (e.g. Bun)

bunx --bun payload run src/seed.ts --disable-transpile

--disable-transpile disables Payload's own transpilation; Bun handles it natively.

Key Takeaways

• getPayload({ config }) works anywhere Node/Bun runs — not just inside Next.js
• Always use payload run for scripts; avoids dotenv vs Next.js env loading conflicts
• Default transpiler is tsx; switch to --use-swc for speed or --disable-transpile for Bun
• Payload is fully ESM — require() / CommonJS scripts won't work
• The same wiki/payloadcms/local-api methods (create, find, update, delete) are available in standalone scripts

Related

• wiki/payloadcms/local-api
• wiki/payloadcms/queries

Sources

• raw/local-api__outside-nextjs.md
• https://payloadcms.com/docs/local-api/outside-nextjs