Installation

Software Requirements

Payload requires the following software:

Any JavaScript package manager (Yarn, NPM, or pnpm - pnpm is preferred)
Node.js version 20.9.0+
Any compatible database (MongoDB or Postgres)

Quickstart with create-payload-app

To quickly scaffold a new Payload app in the fastest way possible, you can use create-payload-app. To do so, run the following command:

1npx create-payload-app@beta

Then just follow the prompts! You'll get set up with a new folder and a functioning Payload app inside. You can then start configuring your application.

Adding Payload to an existing Next.js app is super straightforward. You can either run the npx create-payload-app@beta command inside your Next.js project's folder, or manually install Payload by following the steps below.

If you don't have a Next.js app already, but you still want to start a project from a blank Next.js app, you can create a new Next.js app using npx create-next-app - and then just follow the steps below to install Payload.

1. Install the relevant packages

First, you'll want to add the required Payload packages to your project and can do so by running the command below:

1pnpm i payload@beta @payloadcms/next@beta @payloadcms/richtext-lexical@beta sharp graphql

Next, install a Database Adapter. Payload requires a Database Adapter to establish a database connection. Payload works with all types of databases, but the most common are MongoDB and Postgres.

To install a Database Adapter, you can run one of the following commands:

To install the MongoDB Adapter, run:

1
pnpm i @payloadcms/db-mongodb
To install the Postgres Adapter, run:

1
pnpm i @payloadcms/db-postgres

2. Copy Payload files into your Next.js app folder

Payload installs directly in your Next.js /app folder, and you'll need to place some files into that folder for Payload to run. You can copy these files from the Blank Template on GitHub. Once you have the required Payload files in place in your /app folder, you should have something like this:

1app/
2├─ (payload)/
3├── // Payload files
4├─ (my-app)/
5├── // Your app files

For an exact reference of the (payload) directory, see Project Structure.

The files that Payload needs to have in your /app folder do not regenerate, and will never change. Once you slot them in, you never have to revisit them. They are not meant to be edited and simply import Payload dependencies from @payloadcms/next for the REST / GraphQL API and Admin Panel.

You can name the (my-app) folder anything you want. The name does not matter and will just be used to clarify your directory structure for yourself. Common names might be (frontend), (app), or similar. More details.

3. Add the Payload Plugin to your Next.js config

Payload has a Next.js plugin that it uses to ensure compatibility with some of the packages Payload relies on, like mongodb or drizzle-kit.

To add the Payload Plugin, use withPayload in your next.config.js:

1import { withPayload } from '@payloadcms/next/withPayload'
2
3/** @type {import('next').NextConfig} */
4const nextConfig = {
5  // Your Next.js config here
6  experimental: {
7    reactCompiler: false
8  }
9}
10
11// Make sure you wrap your `nextConfig`
12// with the `withPayload` plugin
13export default withPayload(nextConfig) 

To import the Payload Plugin, you need to make sure your next.config file is set up to use ESM.

You can do this in one of two ways:

Set your own project to use ESM, by adding "type": "module" to your package.json file
Give your Next.js config the .mjs file extension

In either case, all requires and exports in your next.config file will need to be converted to import / export if they are not set up that way already.

4. Create a Payload Config and add it to your TypeScript config

Finally, you need to create a Payload Config. Generally the Payload Config is located at the root of your repository, or next to your /app folder, and is named payload.config.ts.

Here's what Payload needs at a bare minimum:

1import sharp from 'sharp'
2import { lexicalEditor } from '@payloadcms/richtext-lexical'
3import { mongooseAdapter } from '@payloadcms/db-mongodb'
4import { buildConfig } from 'payload'
5
6export default buildConfig({
7  // If you'd like to use Rich Text, pass your editor here
8  editor: lexicalEditor(),
9
10  // Define and configure your collections in this array
11  collections: [],
12
13  // Your Payload secret - should be a complex and secure string, unguessable
14  secret: process.env.PAYLOAD_SECRET || '',
15  // Whichever Database Adapter you're using should go here
16  // Mongoose is shown as an example, but you can also use Postgres
17  db: mongooseAdapter({
18    url: process.env.DATABASE_URI || '',
19  }),
20  // If you want to resize images, crop, set focal point, etc.
21  // make sure to install it and pass it to the config.
22  // This is optional - if you don't need to do these things,
23  // you don't need it!
24  sharp,
25})

Although this is just the bare minimum config, there are many more options that you can control here. To reference the full config and all of its options, click here.

Once you have a Payload Config, update your tsconfig to include a path that points to it:

1{
"compilerOptions": {
  "paths": {
    "@payload-config": [
      "./payload.config.ts"
    ]
  }
},
9}

5. Fire it up!

After you've gotten this far, it's time to boot up Payload. Start your project in your application's folder to get going. By default, the Next.js dev script is pnpm dev (or npm run dev if using NPM).

After it starts, you can go to http://localhost:3000/admin to create your first Payload user!

Deploy your entire stack in one place with Payload Cloud.

Microsoft chose Payload to tell the world about AI.