What Is Payload, and Should You Use It?

If you've used a CMS before, you probably picture a separate service. Something you sign up for, or host somewhere else, and then call over the network from your site. Payload CMS isn't that. It's an open source backend that you define in TypeScript, and it installs inside your Next.js app.

In this post I'll explain what Payload is, how it interacts with your project, and how to tell whether it fits what you're building.

What is Payload CMS?

Payload is an open source backend that you define in TypeScript. It's MIT licensed, so the code is yours to use however you want.

You write one config file, and Payload generates everything else from it. You describe your content in code. Payload builds the database structure, the admin panel your editors work in, and the APIs your frontend reads from. All of it comes out of that one file.

That's what people mean when they call Payload code first. Your content model lives in your repository, next to everything else, and it goes through pull requests like the rest of your code.

How does Payload fit inside a Next.js app?

Payload installs inside your Next.js app. Not beside it, and not on another server. Inside it.

That means one project, one repository, and one deployment. When you push, the site and the CMS go out together.

The way that works is route groups. Payload's files exist in a route group called payload, your own site is in a different one, and Next.js keeps them from colliding. Here's what that looks like:

1src/
2├── app/
3│   ├── (payload)/      the admin panel and the APIs
4│   └── (frontend)/     your site
5├── collections/        your content model, one file each
6└── payload.config.ts   the file everything comes from

There are two route groups inside one app folder, your collections in their own files, and the config at the bottom, which is what generates the admin panel and its APIs.

There's no second project here. No separate repo for the CMS, no API keys between the two halves, and nothing to keep in sync. It's one codebase.

Wiring it up is one line in your Next config, which I cover properly in the next post in this series.

Payload also talks to your database directly. You pick an adapter (MongoDB, Postgres, or SQLite) and the rest of your config doesn't change.

Why the Local API makes Payload different

The consequence of all of this is what makes Payload different from most of what you may have used.

Your pages and your CMS are running in the same process. So a page doesn't have to make an API call to get its content. It can read the database directly.

Payload calls that the Local API, and it's why a Payload site can skip a layer that most stacks need. I'll cover the Local API in its own post later.

In Payload 4, the Next.js integration becomes a framework adapter, with TanStack Start supported alongside it. So Next.js is the first framework Payload runs inside, but it was never supposed to be the only one.

What do you get from one config file?

So far this has been a bit abstract, so let's make it concrete.

Say you're building a site for a client with marketing pages, a blog, a team page, and a contact form. The client wants to edit all of it themselves, and add new blog posts without calling you.

You would simply define the pages, posts, authors, and media in code. They get an admin panel to run it. Your frontend reads it directly.

Once there's a blog, a media gallery, or anything your client updates regularly, that's when Payload earns its place.

It scales past that too. Payload runs storefronts, customer portals, and internal tools. But the client site with a blog is the one most people need.

In fact, Payload makes it easy to build applications that aren't really about content at all. My own project, Riverbed, is an RSS reader built on Payload 4 and TanStack Start. It has the normal marketing pages, sure, but the entire application is built with Payload as its backend.

That means this single config file gives you an admin panel you didn't have to build, with all the bells and whistles you'd expect from a robust backend application, all of which your clients can use without fiddling with code.

From that config, Payload generates four ways to read your data, and you don't write any of them:

• The Local API
• A REST API
• A GraphQL API
• The admin panel itself

You also get:

• Authentication, with users, roles, and password resets already working
• File uploads with image resizing
• Versions and drafts
• Access control on every collection and every field

You didn't build any of that. And because it's your code running on your server, you can change all of it.

There's more in there than I can list here, and I'll get to plenty of it in future posts, like localization, plugins, and hooks.

When should you use Payload, and when should you not?

Payload is a good fit if you want your content model in version control, you need a real admin panel for people who don't write code, and you want to own your hosting.

And to be clear, Payload doesn't require you to use Next.js for your frontend. I get asked that constantly. While the CMS itself is built with Next.js, it's still a headless CMS, so any framework or language can consume it. You just give up some of the benefit of having everything in one application.

But Payload isn't great for every use case. It's a bad fit in four cases.

1. The project is too small for it. If you're building a five-page brochure site that almost never changes, Payload is more than you need. Static pages and a rebuild will serve you better, and you won't be running a database for a few blocks of text and a git hosted image or two.
2. You want a hosted service with no infrastructure to run. Payload isn't that. You're deploying it and you're running a database. As of Figma's acquisition of Payload, there's no first-party cloud version to sign up for.
3. Your team isn't writing TypeScript. Then the whole appeal disappears. The config file is the product, and the config file is TypeScript, extended using TypeScript.
4. Your frontend can't reach your database. You lose the Local API and you're back to calling an API over the network. That still works, but it's not necessarily why you'd choose Payload.

Code first also means a developer has to make every schema change. Your editors can create and edit content all day, but adding a new field is a code change.

For a lot of teams that's what they want. Your content model is reviewed, versioned, and deployed like everything else. For other teams it's a bottleneck. Which one it is depends on your team, not on Payload.

Who owns Payload now?

Payload is owned by Figma, which acquired it in June 2025.

It's still MIT licensed and still open source, and I believe it will remain so. There's been no slowing down from the team when it comes to improving the open source side of the project. The code is yours, your data stays yours, and the licence didn't change with the acquisition.

What did change is hosting. Payload Cloud, the managed option, closed to new signups after the acquisition. Existing customers carry on, but new projects host it themselves.

And lastly, Payload 4 is coming, with a redesigned admin panel and the framework adapter work I mentioned earlier. You can get an early look at it by joining Payload's official Discord.

Wrapping up

And that's all there is to it! You now know what Payload is, you know it can be inside your Next.js app rather than beside it, and you've got a real sense of whether it fits your project.

If you'd like a sequential set of videos covering a full Payload setup, that's what my course, Payload Essentials, is for.