---
title: "Payload Local API — Outside Next.js"
aliases: [payload-standalone, payload-scripts, payload-outside-nextjs]
tags: [payloadcms, local-api, standalone, scripts, esm]
sources: [raw/local-api__outside-nextjs.md]
created: 2026-05-15
updated: 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:

```ts
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:

```sh
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)

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

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

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

```sh
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|Local API]] methods (`create`, `find`, `update`, `delete`) are available in standalone scripts

## Related

- [[wiki/payloadcms/local-api|Local API — full reference]]
- [[wiki/payloadcms/queries|Queries — where, depth, pagination]]

## Sources

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