outside-nextjs.mdx

title	label	order	desc	keywords
Using Payload outside Next.js	Outside Next.js	20	Payload can be used outside of Next.js within standalone scripts or in other frameworks like Remix, SvelteKit, Nuxt, and similar.	local api, config, configuration, documentation, Content Management System, cms, headless, javascript, node, react, express

Payload can be used completely outside of Next.js which is helpful in cases like running scripts, using Payload in a separate backend service, or using Payload's Local API to fetch your data directly from your database in other frontend frameworks like SvelteKit, Remix, Nuxt, and similar.

**Note:** Payload and all of its official packages are fully ESM. If you want to use Payload within your own projects, make sure you are writing your scripts in ESM format or dynamically importing the Payload Config.

Importing the Payload Config outside of Next.js

Payload provides a convenient way to run standalone scripts, which can be useful for tasks like seeding your database or performing one-off operations.

In standalone scripts, you can simply import the Payload Config and use it right away. If you need an initialized copy of Payload, you can then use the getPayload function. This can be useful for tasks like seeding your database or performing other one-off operations.

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

const seed = async () => {
  // Get a local copy of Payload by passing your config
  const payload = await getPayload({ config })

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

  const page = await payload.create({
    collection: 'pages',
    data: {
      title: 'My Homepage',
      // other data to seed here
    },
  })
}

// Call the function here to run your seed script
await seed()

You can then execute the script using payload run. Example: if you placed this standalone script in src/seed.ts, you would execute it like this:

payload run src/seed.ts

The payload run command does two things for you:

1. It loads the environment variables the same way Next.js loads them, eliminating the need for additional dependencies like dotenv. The usage of dotenv is not recommended, as Next.js loads environment variables differently. By using payload run, you ensure consistent environment variable handling across your Payload and Next.js setup.
2. It initializes tsx, allowing direct execution of TypeScript files manually installing tools like tsx or ts-node.

Troubleshooting

If you encounter import-related errors, you have 2 options:

Option 1: enable swc mode by appending --use-swc to the payload command:

Example:

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

Note: Install @swc-node/register in your project first. While swc mode is faster than the default tsx mode, it might break for some imports.

Option 2: use an alternative runtime like bun

While we do not guarantee support for alternative runtimes, you are free to use them and disable Payload's own transpilation by appending the --disable-transpile flag to the payload command:

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

You will need to have bun installed on your system for this to work.