Headless CMS often becomes a 'black box': you can't change the admin logic, add a custom endpoint, or embed authentication without workarounds. Payload solves this radically — it lives in your repository as an ordinary npm library. We use Payload in production on high-traffic projects and know all its pitfalls.
Why Payload Instead of Strapi or Contentful?
Payload is not a service, not SaaS. It's an npm package that mounts into Express or Next.js. You don't pay a license fee and are not vendor-locked. Unlike Strapi, where customizing the admin requires forking the repository, in Payload you write a TypeScript config and get a fully controllable backend. Contentful is convenient if you have a large content team and need guaranteed uptime, but flexibility costs €5000+/month. Payload is 2x faster than Strapi when loading lists thanks to N+1 query optimization and tree-shaking. Payload is a headless CMS and application framework that is developer-friendly and flexible.
When Payload Makes Sense
The product fits when you need full control over the data schema, custom authentication, or when the CMS needs to embed into an existing backend. Payload doesn't require separate hosting — it runs where your API lives.
Don't use it if your content team is large and used to cloud CMS with guaranteed uptime — then Contentful or Prismic are simpler.
How to Configure Collections and Globals?
Typical project structure: src/payload.config.ts — main config, src/collections/ — content types (e.g., Posts, Users, Media), src/globals/ — singleton documents (e.g., SiteSettings). Steps:
- Create a collection file (e.g., Posts.ts) and define fields with types and access.
- Import the collection into payload.config.ts.
- Configure the database adapter and editor.
- For globals, create a similar file in
src/globals/and add to config.
Example posts collection with Access Control and versioning:
// src/collections/Posts.ts
import { CollectionConfig } from 'payload/types'
const Posts: CollectionConfig = {
slug: 'posts',
admin: {
useAsTitle: 'title',
defaultColumns: ['title', 'status', 'publishedAt'],
},
access: {
read: ({ req: { user } }) => {
if (user) return true
return { status: { equals: 'published' } }
},
create: ({ req: { user } }) => Boolean(user?.roles?.includes('editor')),
update: ({ req: { user } }) => Boolean(user?.roles?.includes('editor')),
},
versions: {
drafts: { autosave: true },
maxPerDoc: 20,
},
fields: [
{ name: 'title', type: 'text', required: true },
{ name: 'slug', type: 'text', unique: true, admin: { position: 'sidebar' } },
{
name: 'content',
type: 'richText',
editor: lexicalEditor({
features: ({ defaultFeatures }) => [
...defaultFeatures,
HTMLConverterFeature({}),
],
}),
},
{
name: 'featuredImage',
type: 'upload',
relationTo: 'media',
},
{
name: 'status',
type: 'select',
options: ['draft', 'published'],
defaultValue: 'draft',
admin: { position: 'sidebar' },
},
{
name: 'publishedAt',
type: 'date',
admin: { position: 'sidebar', date: { pickerAppearance: 'dayAndTime' } },
},
],
}
export default Posts
Global config includes database and editor adapters:
// src/payload.config.ts
import { buildConfig } from 'payload/config'
import { mongooseAdapter } from '@payloadcms/db-mongodb'
import { lexicalEditor } from '@payloadcms/richtext-lexical'
import Posts from './collections/Posts'
import Users from './collections/Users'
import Media from './collections/Media'
export default buildConfig({
serverURL: process.env.PAYLOAD_PUBLIC_SERVER_URL,
admin: {
user: Users.slug,
bundler: webpackBundler(),
},
editor: lexicalEditor({}),
collections: [Posts, Users, Media],
db: mongooseAdapter({ url: process.env.DATABASE_URI! }),
// or PostgreSQL:
// db: postgresAdapter({ pool: { connectionString: process.env.DATABASE_URI } }),
upload: {
limits: { fileSize: 10_000_000 },
},
localization: {
locales: ['ru', 'en'],
defaultLocale: 'ru',
fallback: true,
},
})
Payload supports MongoDB and PostgreSQL. For PostgreSQL, migrations are generated automatically: npx payload migrate:create && npx payload migrate.
How to Integrate Payload with Next.js 14?
Since version 2.x, Payload supports mounting into Next.js App Router. All code fits in two files:
// app/(payload)/admin/[[...segments]]/page.tsx
import { RootPage } from '@payloadcms/next/views'
import config from '@payload-config'
export default RootPage.bind(null, { config })
// app/(payload)/api/[...slug]/route.ts
import { REST_DELETE, REST_GET, REST_PATCH, REST_POST } from '@payloadcms/next/routes'
import config from '@payload-config'
export const GET = REST_GET.bind(null, config)
export const POST = REST_POST.bind(null, config)
export const PATCH = REST_PATCH.bind(null, config)
export const DELETE = REST_DELETE.bind(null, config)
This means one next start, one process, one deployment.
Hooks, Endpoints, and Media
Hooks on collections allow reacting to data changes. For example, auto-generating slug or cache revalidation:
// inside collection Posts
hooks: {
beforeChange: [
async ({ data, operation }) => {
if (operation === 'create') {
data.slug = slugify(data.title)
}
return data
},
],
afterChange: [
async ({ doc }) => {
await revalidatePath(`/blog/${doc.slug}`)
},
],
},
endpoints: [
{
path: '/:id/publish',
method: 'post',
handler: async (req, res) => {
await payload.update({
collection: 'posts',
id: req.params.id,
data: { status: 'published', publishedAt: new Date() },
})
res.json({ message: 'Published' })
},
},
],
// media collection with image generation
const Media: CollectionConfig = {
slug: 'media',
upload: {
staticURL: '/media',
staticDir: 'media',
imageSizes: [
{ name: 'thumbnail', width: 400, height: 300, crop: 'centre' },
{ name: 'card', width: 768, height: 1024 },
{ name: 'hero', width: 1920, height: undefined },
],
adminThumbnail: 'thumbnail',
mimeTypes: ['image/*', 'application/pdf'],
},
fields: [{ name: 'alt', type: 'text' }],
}
For S3 — the official plugin @payloadcms/plugin-cloud-storage with adapters for S3, GCS, or Azure.
Storage Comparison: Local vs S3
| Feature | Local Storage | S3 (Cloud Storage) |
|---|---|---|
| Speed | High | Medium (latency 30-100ms) |
| Scalability | Disk-limited | Automatic |
| Backup | Manual | Built-in |
| Cost | Only disk | $0.023/GB + requests |
Work Stages and Timeline
| Stage | Approximate Time |
|---|---|
| Content model analysis | 1 day |
| Collection and global development | 2–3 days |
| Access Control and role setup | 1 day |
| Next.js integration | 1 day |
| Media and backup configuration | 0.5 day |
| Deployment and documentation | 1 day |
What's Included in the Work
- Development of collection and global schemas for your content
- Setup of Access Control and Roles
- Integration with Next.js or Nuxt (App Router)
- Media and backup configuration
- Server deployment (Docker, Nginx)
- API documentation (Postman/Swagger)
- Training editors on admin panel usage
- 30-day warranty on bugs
Timeline and Cost
Basic integration (3–4 collections, localization, Next.js) takes 5–7 days. If custom authentication, RBAC, or complex hooks are needed, from 2 weeks. Cost is calculated individually, but savings on licenses and infrastructure can reach 50% compared to cloud CMS. Time-to-market is reduced by 30%, and the number of database queries is halved due to proper depth configuration.
Typical Mistakes and How to Avoid Them
- N+1 queries when using depth > 2 — disable populate when not needed
- Missing indexes for slug and dates — add
index: trueto fields - Mixing environments — keep .env separate for development and production
- Wrong MIME types — explicitly set
mimeTypesin media collection
We are a team with 7+ years of experience in Node.js and 50+ projects with headless CMS. Order a turnkey Payload CMS integration. We'll set everything up in 5–7 days. Contact us for a project evaluation.