Step-by-Step Guide to Getting Started with PayloadCMS [& Adding It to an Existing Next.js Project]

In this guide, we’re going to talk about how to get started with Payload CMS.

To get started with Payload CMS, you can go to their getting started guide in their documentation on their website.

Go to installation and make sure you have the required software installed on your machine. You can either have MongoDB or Postgres installed on your computer, or you can use a hosted version of either of these databases—like MongoDB Atlas or Vercel—and connect to them that way.

To get started with a new project

Open your terminal, go to the location where you want to start a new project, and enter the command npx create-payload-app. This will then give you several prompts. Once you get through the prompts, you can navigate to the folder created from the Payload command line interface (CLI) tool and open it in your IDE of choice.

Get started with an existing project

Now, getting started with Payload CMS in an existing project is more involved, but it’s still relatively easy. To show you how to do this, I’m going to create a new NextJS app using create-next-app.

So, again, we’ll go to our terminal and type npx create-next-app and hit enter. It’ll prompt you through the options you need and very quickly get you set up with a new NextJS project.

You’ll need to install relevant packages including the Payload CMS package and a database adapter. After that, you can copy the default Payload files into your Next.js app folder.

To do this, you can either go in and manually copy the files over, but since that’s extremely error prone, I’m going to download the files from their git repository and copy them from there.

In order to do this, you need to go to Payload’s git repository on Github. You will need to login, so if you don’t have a Github account, be sure to sign up for one before moving forward. Once you’re at the Github repository, you’ll need to find their main branch, called payload. When you click on that, you’ll see a green “code” button that you can click on and click download ZIP.

This should prompt you to download the git repository to your computer, which you can then unzip. You’ll then need to locate the files you’re looking for by going to payload > app, then just copy the (payload) directory and paste it in your new project.

With how Payload is set up, you will need to create another separate folder for your frontend. The way Payload CMS is coupled with your frontend is by being placed in your app folder, but to keep everything separate, the Payload files need to be in a (payload) page group, which we just brought in, and everything else needs to be in a page group named anything else you want it to be. This can be (frontend) or (app). It just needs to be separate.

After that, you need to add the Payload Plugin to your Next.js config file. You may need to make sure you Next.js config file is set up to use ESM by adding ”type”: “module” to your package.json file or giving your Next.js config a .mjs file extension. Either will work, but if you have anything that uses require() in your project, they will need to be updated to import and export.

Lastly, you’ll need to create a Payload Config file to add to your TypeScript config.

If you haven’t already done so, add a file named payload.config.ts to your root folder (or next to /app).

The bare minimum you need to start your project is included in the docs.

You can extend way beyond this, but we’re just trying to get the project started, so we’ll use the bare minimum here.

After all that is done, update your tsconfig to include a path.

You can then fire up the project with npm run dev or pnpm dev and navigate to http://localhost:3000/admin. Assuming we did everything right, it should load right up and ask you to create your first user.

Final Thoughts 

That’s it for getting started with PayloadCMS. While creating a new Payload project is rather simple, it can be more involved and tricky to add Payload to an existing project. Once it’s all set up, though, it’s simple to get started.