Payload CMS Integration for Content Management

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:

1. Create a collection file (e.g., Posts.ts) and define fields with types and access.
2. Import the collection into payload.config.ts.
3. Configure the database adapter and editor.
4. 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

Work Stages and Timeline

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: true to fields
• Mixing environments — keep .env separate for development and production
• Wrong MIME types — explicitly set mimeTypes in 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.