Custom Payload CMS Collections Development
Imagine: you need to organize a product catalog with variants (size, color, stock), an SEO block, and access rights for different roles. Regular CMSes don't offer such flexibility—you have to write custom plugins or migrate to a headless solution. Payload CMS solves this at the architecture level: collections, hooks, and access control allow you to build any business logic without compromises. We configure a collection to perfectly match your processes. Let's break it down with a practical example of building a product catalog for an online store. Time savings on API development — up to 50% compared to custom-built solutions.
How We Build the Product Collection
We start with configuration. Each collection is a TypeScript object with fields, access settings, and hooks. Here's a minimal structure:
// collections/Products.ts
import { CollectionConfig } from 'payload/types'
const Products: CollectionConfig = {
slug: 'products',
labels: {
singular: 'Product',
plural: 'Products',
},
admin: {
useAsTitle: 'name',
defaultColumns: ['name', 'price', 'category', 'inStock'],
group: 'Catalog',
},
// ...
}
Then we elaborate the fields in detail. Payload is 2 times more flexible in field configuration than Strapi: it supports blocks, arrays, and groups. Below is a real set of fields for a product with variants and an SEO block:
fields: [
// Text fields
{ name: 'name', type: 'text', required: true },
{ name: 'description', type: 'textarea' },
{ name: 'content', type: 'richText' },
// Price and publication date
{ name: 'price', type: 'number', min: 0, required: true },
{ name: 'publishedAt', type: 'date' },
// Product status
{
name: 'status',
type: 'select',
options: [
{ label: 'Active', value: 'active' },
{ label: 'Archived', value: 'archived' },
],
defaultValue: 'active',
},
// Image
{ name: 'image', type: 'upload', relationTo: 'media' },
// Relationships to categories and tags
{
name: 'category',
type: 'relationship',
relationTo: 'categories',
hasMany: false,
},
{
name: 'tags',
type: 'relationship',
relationTo: 'tags',
hasMany: true,
},
// Array of variants (SKU, color, size, stock)
{
name: 'variants',
type: 'array',
fields: [
{ name: 'sku', type: 'text', required: true },
{ name: 'color', type: 'text' },
{ name: 'size', type: 'text' },
{ name: 'stock', type: 'number', defaultValue: 0 },
],
},
// Blocks for dynamic sections (e.g., description, features, CTA)
{
name: 'sections',
type: 'blocks',
blocks: [TextBlock, ImageBlock, CTABlock],
},
// Group for SEO metadata
{
name: 'seo',
type: 'group',
fields: [
{ name: 'title', type: 'text' },
{ name: 'description', type: 'textarea' },
],
},
]
Why Do You Need beforeChange and afterChange Hooks?
Without hooks, a collection is just CRUD. Hooks add business logic. We use beforeChange to generate a slug based on the product name and to automatically set the author. afterChange is used for invalidating the Next.js cache or sending notifications to Telegram. Here's what a typical set of hooks looks like in our project:
hooks: {
beforeChange: [
async ({ data, req, operation }) => {
if (operation === 'create' && !data.slug) {
data.slug = data.name
.toLowerCase()
.replace(/\s+/g, '-')
.replace(/[^\w-]/g, '')
}
if (operation === 'create' && req.user) {
data.author = req.user.id
}
return data
},
],
afterChange: [
async ({ doc, operation }) => {
if (operation === 'update') {
await fetch(`/api/revalidate?path=/products/${doc.slug}`, {
method: 'POST',
})
}
},
],
afterDelete: [
async ({ doc }) => {
console.log(`Product ${doc.id} deleted`)
},
],
},
How to Configure Access to the Collection?
Access control in Payload is flexible: you can define rules for read, create, update, and delete. We often encounter requests like: "read - everyone, create - authenticated, update - only author or admin." This is implemented through conditional filters. Example:
access: {
read: () => true,
create: ({ req: { user } }) => Boolean(user),
update: ({ req: { user }, id }) => {
if (!user) return false
if (user.role === 'admin') return true
return { author: { equals: user.id } }
},
delete: ({ req: { user } }) => user?.role === 'admin',
},
Custom Validation
Sometimes standard field types do not cover the requirements. For example, you need to check the uniqueness of SKU among all product variants. For that, we use the validate function in the array field. The validation code executes on the server before saving, ensuring data integrity. Example:
{
name: 'variants',
type: 'array',
fields: [
{ name: 'sku', type: 'text', required: true, unique: true },
],
validate: (value) => {
const skus = value.map(v => v.sku)
if (new Set(skus).size !== skus.length) return 'SKU must be unique'
return true
},
}
Versioning and Data Retrieval via API
For content projects, we enable versioning. Payload stores up to 20 versions with auto-save every 2 seconds. This is indispensable when multiple editors work on the content. After configuring the collection, REST and GraphQL endpoints are automatically generated. Here's an example of a server-side request (Next.js Server Component) with filtering:
import { getPayload } from 'payload'
import config from '@payload-config'
const payload = await getPayload({ config })
const result = await payload.find({
collection: 'products',
where: {
and: [
{ status: { equals: 'active' } },
{ category: { equals: categoryId } },
{ price: { less_than: 10000 } },
],
},
sort: '-createdAt',
limit: 20,
page: 1,
depth: 2,
})
const { docs, totalDocs, hasNextPage } = result
Field Type Comparison
| Type | Purpose | Example Use Case |
|---|---|---|
| text | Short text | Product name |
| textarea | Long text | Product description |
| richText | Formatted content | Blog article |
| number | Numeric value | Price, quantity |
| date | Date/time | Publication date |
| select | Selection from list | Product status |
| relationship | Link to another collection | Category, tags |
| array | Array of objects | Product variants |
| blocks | Block editor (Gutenberg) | Page sections |
| group | Grouping fields | SEO metadata |
Comparison of Payload with Other Headless CMS
| Criterion | Payload | Strapi | Directus |
|---|---|---|---|
| Field flexibility | Maximum: blocks, arrays | Medium: basic types only | High: custom fields |
| Hooks and events | Full: beforeChange, after... | Middleware | Input/output hooks |
| Access control | Granular: read/create/... | Roles and permissions | Permissions + filters |
| Versioning | Built-in, auto-save | Plugins | Plugins |
| Performance | Fast on PostgreSQL/MySQL | Medium | High on MySQL |
This allows saving up to 40% of the budget compared to similar solutions on Strapi.
Typical Mistakes When Creating Collections
- Using textarea instead of richText — loss of formatting.
- Missing slug uniqueness validation — duplicate URLs.
- Too open access — data leaks.
- Ignoring hooks — business logic remains on the client.
What's Included in Development and Timeline
We design the field and relationship schema with future extensions in mind, write hooks, and configure access control. Setting up one collection takes 2–4 hours. A full catalog of 5–10 interrelated collections takes 2–4 days. The cost of developing one collection is comparable to several developer days, which is significantly cheaper than building similar functionality on a custom solution. Included: integration with an existing database, API documentation, and team training. Get a consultation for a free evaluation of your project.
Order custom Payload CMS collections development — get a ready API in 2–4 days. Our engineers have been working with Payload since version 1.0 and are certified in Next.js and TypeScript. Over the years, we have implemented more than 50 projects on Payload. We guarantee that the collections will meet your requirements and scale easily.