Skip to content
Get packs

Guide · Open source

How to use Payload: install, run and build with it

Updated · written with AI from the project's own documentation and checked against our catalogue data

Payload is an open-source, fullstack Next.js framework that gives you a TypeScript backend, a database-backed API and an admin panel. It suits developers who already build with Next.js and React and want a backend without running a separate server. This guide walks you through the prerequisites, the install commands from the project README, and the main features to know before you build.

Payloadpayloadcms/payload · ★ 45.6k · MIT

Quick start

  1. 1Check prerequisites. Install Node.js and pnpm or npm. Confirm that you can run npx or pnpx from your terminal.
  2. 2Create the app. Run pnpx create-payload-app@latest to start a new project, or add -t website to use the website template.
  3. 3Open the project. Move into the generated folder and review the /app folder, which holds both the frontend and backend code in the website template.
  4. 4Explore the admin panel. Use the admin panel to add and edit content, then check how fields, access control and drafts are set up.
  5. 5Customise in code. Extend the admin with server components or change collections, hooks and access rules in TypeScript.
  6. 6Deploy or self-host. Choose a host. The README lists one-click options for Vercel and Cloudflare, or you can deploy elsewhere.

What you need before you install Payload

Payload is built on Next.js and TypeScript, and the project README centres on that stack. Before you start, the README asks you to check the required software list in the official installation docs.

The README lists Node.js and either pnpm or npm (used for npx or pnpx) as the prerequisites.

  • Node.js
  • pnpm or npm (for npx/pnpx)

Create a new Payload app with create-payload-app

The quickest way to start is the create-payload-app tool. Running it with pnpx creates a new Payload project for you.

The README recommends the website template if you are new to Payload. It shows how to do everything, including custom Rich Text blocks, on-demand revalidation and live preview. The template comes with a Tailwind frontend in one /app folder.

  • Create a new Payload app: run the create-payload-app command with pnpx.
  • Create a project from the website template: add the -t website flag.
pnpx create-payload-app@latest pnpx create-payload-app@latest -t website

Explore the built-in features

Payload includes several features out of the box. You do not need to build them yourself before you can start working with content.

Auth, versions and drafts, localization, a block-based layout builder and a Lexical rich text editor are all listed in the README. Access control and hooks let you control who can do what and run logic on each action.

  • Auth out of the box
  • Versions and drafts
  • Localization
  • Block-based layout builder
  • Customizable React admin
  • Lexical rich text editor
  • Conditional field logic
  • Access control
  • Document and field-level hooks
  • Query your database directly in server components

Deploy Payload with one click

The README lists one-click deployment options for Cloudflare and Vercel. The Cloudflare option uses Workers, R2 for uploads and D1 for the database. The Vercel option uses a Next.js front end, a Neon database and Vercel Blob for media.

Because Payload is self-hosted software, you are responsible for the hosting and database choices you make.

  • Cloudflare: Workers, R2 for uploads, D1 for the database
  • Vercel: Next.js front end, Neon database, Vercel Blob for media

Get help, templates and plugins

The README points to the official docs, GitHub Discussions, GitHub Issues and a Discord server for help. Community templates and plugins are listed under GitHub topics.

To run an example from the examples directory, the README shows how to use create-payload-app with the --example flag.

  • Docs: payloadcms.com/docs
  • Community help: payloadcms.com/community-help
  • Examples directory in the repository
  • Official and community plugins
npx create-payload-app --example example_name

What people use it for

  • Building a marketing website with a headless CMS and a Next.js front end, using the website template
  • Running an ecommerce store with the ecommerce template listed in the README
  • Creating a blog or portfolio where editors use the admin panel to publish drafts
  • Building a custom application that needs user auth and access control in the same codebase
  • Querying your database directly inside React Server Components

Frequently asked questions

Is Payload free to use?

Yes. The README describes Payload as completely free and open-source, and the licence is MIT. You still pay for any hosting or database services you choose to use.

What do I need to install Payload?

The README lists Node.js and either pnpm or npm, which gives you npx or pnpx. You also need to have the required software set up as described in the official installation docs.

Do I need to know TypeScript or Next.js?

Yes. Payload is a Next.js framework and is fully TypeScript. The README says it is not for projects that do not use Next.js or TypeScript, and it is not a point-and-click site builder.

Can Payload be used as a headless CMS?

Yes. The project describes Payload as both an app framework and a headless CMS. You can also use it as the backend for a larger application in the same codebase.

What are the alternatives to Payload?

The README lists Strapi, Directus, Sanity and Keystone as comparable projects. Choose based on your stack, whether you want to self-host, and how much you want to customise in code.

Can I deploy Payload for free?

The README says you can deploy Payload serverlessly on Vercel for free and offers one-click options for Vercel and Cloudflare. Check each provider's own pricing and limits before you deploy.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Payload suits developers who already use Next.js and React and want a self-hosted, customisable backend and admin panel in one codebase. It is a poor fit for non-developers who want a point-and-click builder, or for teams that want a fully managed service with no hosting or database work.

Install options & downloads