PayloadCMS — Getting Started

Overview

Payload is a code-first, open-source Next.js fullstack framework that acts as a CMS, enterprise tool builder, or headless commerce platform. Write a payload.config.ts and get an auto-generated Admin Panel, REST/GraphQL/Local APIs, database schema with migrations, auth, and file upload out of the box. Self-hostable anywhere Node.js runs, including Vercel serverless.

Key Concepts

Config — central payload.config.ts file; fully typed JS object; everything derives from it
Collections — groups of Documents sharing a schema (e.g. pages, posts, users)
Globals — singleton Documents (e.g. site header, nav); same APIs as Collections but one doc only
Fields — schema building blocks; define DB columns + Admin UI simultaneously
Hooks — lifecycle callbacks (before/after read, create, update, delete)
Access Control — per-collection/global functions controlling what each user can do
Local API — direct-to-DB Node.js API, zero HTTP overhead, fully typed
REST API — auto-mounted at /api/<collection-slug>
GraphQL API — auto-mounted at /api/graphql, playground at /api/graphql-playground
Admin Panel — Next.js App Router React app, auto-generated from config, fully extensible

Requirements

Node.js 24.15.0+
Next.js 16.2.6+
pnpm (preferred), npm, or yarn 2+
One DB: MongoDB, PostgreSQL, or SQLite

API / Config Reference

Minimal `payload.config.ts`

import sharp from 'sharp'
import { lexicalEditor } from '@payloadcms/richtext-lexical'
import { mongooseAdapter } from '@payloadcms/db-mongodb'
import { buildConfig } from 'payload'

export default buildConfig({
  editor: lexicalEditor(),
  collections: [],
  secret: process.env.PAYLOAD_SECRET || '',
  db: mongooseAdapter({
    url: process.env.DATABASE_URL || '',
  }),
  sharp,
})

Core TypeScript types

import { Config, CollectionConfig, GlobalConfig, Field } from 'payload'
import type { Config, SanitizedConfig } from 'payload'

`tsconfig.json` path alias (required)

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

`next.config.js` wrapper (required)

import { withPayload } from '@payloadcms/next/withPayload'

const nextConfig = {}

export default withPayload(nextConfig)

next.config must be ESM — either add "type": "module" to package.json or use .mjs extension.

Code Examples

Quickstart

npx create-payload-app
# or target a template:
npx create-payload-app@latest -t website
npx create-payload-app@latest -t blank

Manual install packages

pnpm i payload @payloadcms/next
pnpm i @payloadcms/richtext-lexical sharp graphql
pnpm i @payloadcms/db-mongodb   # or db-postgres, db-sqlite

Local API usage in React Server Component

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

const MyServerComponent: React.FC = async () => {
  const payload = await getPayload({ config })
  const findResult = await payload.find({ collection: 'pages' })
  // findResult.docs is typed as Page[]
}

REST API

fetch('https://localhost:3000/api/pages')
  .then((res) => res.json())
  .then((data) => console.log(data))

App folder structure after install

app/
├─ (payload)/      # Payload files — do NOT edit
├─ (my-app)/       # Your frontend files

Package Architecture

Package	Role
`payload`	Core business logic, Local API, TypeScript types
`@payloadcms/next`	Admin Panel, REST API, GraphQL HTTP layer
`@payloadcms/ui`	Reusable Admin UI React components
`@payloadcms/db-*`	Database adapters (one per project)
`@payloadcms/richtext-lexical`	Rich text editor (optional)
`@payloadcms/graphql`	GraphQL layer (bundled in `@payloadcms/next`)

Gotchas

All official Payload packages must use matching version numbers — mixing versions breaks things
withPayload is ESM only; require() in next.config.js will fail
next.cacheComponents has partial compatibility — not fully supported alongside Payload
yarn 1.x is not supported; use pnpm, npm, or yarn 2+
The (payload) app folder files are not meant to be edited and will not regenerate
sharp is optional but required for image cropping, resizing, focal point selection
graphql package must be in your package.json explicitly if you use GraphQL queries

4.8 KiB Raw Blame History