Payload CMS Plugin Development
Imagine you have 10 collections, and each needs the same SEO fields—meta title, description, image, and a noIndex flag. Manual addition takes 2-3 hours per collection, and maintenance can cost $1,000 annually for a project with 10 collections. Payload CMS plugins solve this problem once and for all: you describe the fields once in the plugin code, then attach it to the needed collections with a single line. We develop such plugins turnkey with quality guarantees and support. Our experience: over 5 years and 15+ plugins for various projects. If you need a plugin, contact us for a consultation.
Why Plugins Are Beneficial
The main issue is code duplication. If functionality is needed in multiple collections, copying fields and hooks bloats the codebase. The second problem is maintenance complexity: changing logic requires edits in every place. The third is the lack of a unified interface for similar operations. Plugins centralize functionality: SEO, audit, search, custom endpoints. For example, an SEO plugin adds identical meta-fields to all specified collections, while an audit plugin logs all changes into a single log collection. Plugins are 3 times faster to implement than manual coding and reduce development time by 40%. Implementation costs are recouped within months due to reduced maintenance. Comparison with manual addition: a plugin is 3-4 times faster to maintain and less error-prone.
How to Develop a Plugin for Payload CMS
According to the official Payload CMS documentation, a plugin is "a function that takes a configuration and returns a modified configuration." No magic: the plugin simply adds collections, fields, hooks, endpoints, and components to the existing configuration before initializing the CMS. The official plugins (@payloadcms/seo, @payloadcms/form-builder) follow the same model.
// Plugin type
type Plugin = (incomingConfig: Config) => Config
// Simplest plugin
const myPlugin: Plugin = (config) => {
return {
...config,
collections: [
...(config.collections || []),
// add a collection
],
hooks: {
...config.hooks,
afterInit: [
...(config.hooks?.afterInit || []),
// add a hook
],
},
}
}
export default buildConfig({
plugins: [myPlugin],
})
Example Plugins: SEO, Audit, Search
The Payload plugin architecture is simple yet powerful. An SEO plugin adds meta-fields to all specified collections:
// plugins/seo/index.ts
import type { Config, CollectionConfig, GlobalConfig } from 'payload/types'
interface SEOPluginConfig {
collections?: string[] // slugs of collections to add SEO fields
globals?: string[]
uploadsCollection?: string
generateTitle?: (doc: any) => string
generateDescription?: (doc: any) => string
}
export const seoPlugin = (pluginConfig: SEOPluginConfig) => (config: Config): Config => {
const seoFields = [
{
name: 'meta',
type: 'group' as const,
label: 'SEO',
admin: { position: 'sidebar' as const },
fields: [
{
name: 'title',
type: 'text' as const,
admin: {
description: ({ doc }: any) =>
pluginConfig.generateTitle?.(doc) || 'Auto-fill: document title',
},
},
{
name: 'description',
type: 'textarea' as const,
maxLength: 160,
},
{
name: 'image',
type: 'upload' as const,
relationTo: pluginConfig.uploadsCollection || 'media',
},
{
name: 'noIndex',
type: 'checkbox' as const,
defaultValue: false,
},
],
},
]
return {
...config,
collections: config.collections?.map(collection => {
if (pluginConfig.collections?.includes(collection.slug)) {
return {
...collection,
fields: [...(collection.fields || []), ...seoFields],
}
}
return collection
}),
globals: config.globals?.map(global => {
if (pluginConfig.globals?.includes(global.slug)) {
return {
...global,
fields: [...(global.fields || []), ...seoFields],
}
}
return global
}),
hooks: {
...config.hooks,
afterRead: [
...(config.hooks?.afterRead || []),
({ doc }: any) => {
if (!doc.meta?.title && pluginConfig.generateTitle) {
doc.meta = {
...doc.meta,
title: pluginConfig.generateTitle(doc),
}
}
return doc
},
],
},
}
}
An audit plugin logs all changes:
// plugins/audit-log/index.ts
import type { Config } from 'payload/types'
interface AuditLogConfig {
collections: string[]
}
export const auditLogPlugin = ({ collections }: AuditLogConfig) => (config: Config): Config => {
const auditCollection = {
slug: 'audit-logs',
admin: { hidden: true },
access: {
read: ({ req }: any) => req.user?.role === 'admin',
create: () => false,
update: () => false,
delete: () => false,
},
fields: [
{ name: 'collection', type: 'text' as const },
{ name: 'docId', type: 'text' as const },
{ name: 'operation', type: 'text' as const },
{ name: 'user', type: 'relationship' as const, relationTo: 'users' as const },
{ name: 'before', type: 'json' as const },
{ name: 'after', type: 'json' as const },
{ name: 'timestamp', type: 'date' as const },
],
}
const auditedCollections = config.collections?.map(collection => {
if (!collections.includes(collection.slug)) return collection
return {
...collection,
hooks: {
...collection.hooks,
afterChange: [
...(collection.hooks?.afterChange || []),
async ({ doc, previousDoc, operation, req }: any) => {
if (!req.payload) return
await req.payload.create({
collection: 'audit-logs',
data: {
collection: collection.slug,
docId: String(doc.id),
operation,
user: req.user?.id,
before: previousDoc || null,
after: doc,
timestamp: new Date().toISOString(),
},
disableVerificationEmail: true,
})
},
],
},
}
})
return {
...config,
collections: [
...(auditedCollections || []),
auditCollection,
],
}
}
A search plugin adds a custom /search endpoint:
// plugins/search/index.ts
export const searchPlugin = (config: Config): Config => ({
...config,
endpoints: [
...(config.endpoints || []),
{
path: '/search',
method: 'get' as const,
handler: async (req: any, res: any) => {
const { q } = req.query
if (!q) return res.json({ docs: [] })
const results = await Promise.all([
req.payload.find({
collection: 'posts',
where: { or: [{ title: { like: q } }, { excerpt: { like: q } }] },
limit: 5,
}),
req.payload.find({
collection: 'products',
where: { name: { like: q } },
limit: 5,
}),
])
return res.json({
docs: [
...results[0].docs.map(d => ({ ...d, _type: 'post' })),
...results[1].docs.map(d => ({ ...d, _type: 'product' })),
],
})
},
},
],
})
Publishing a Plugin as an npm Package
// plugin package.json
{
"name": "@myorg/payload-plugin-seo",
"version": "1.0.0",
"main": "dist/index.js",
"types": "dist/index.d.ts",
"peerDependencies": {
"payload": "^2.0.0"
},
"scripts": {
"build": "tsc"
}
}
Export the plugin from src/index.ts: export { seoPlugin } from './plugin'; export type { SEOPluginConfig } from './types';. After build, publish to npm. Documentation in README is mandatory.
Comparison of Plugin Types
| Plugin Type | Purpose | Complexity | Example Usage |
|---|---|---|---|
| SEO | Add meta fields | Low | seoPlugin({ collections: ['posts'] }) |
| Audit | Log changes | Medium | auditLogPlugin({ collections: ['posts'] }) |
| Search | Custom endpoint | High | searchPlugin() |
Hook Types Used in Plugins
| Hook | Purpose | Example in Plugin |
|---|---|---|
| beforeChange | Validation before save | Check slug uniqueness |
| afterChange | Log changes | Audit plugin |
| beforeRead | Modify data before read | Auto-fill meta fields |
| afterRead | Post-processing | SEO plugin (add meta title) |
Plugin Development Process
- Requirements analysis: determine collections, hooks, and endpoints. Consider potential collisions with existing fields.
- Interface design: create TypeScript types for the plugin configuration. Use strict typing to avoid errors at compile time.
- Implementation: write the plugin code, use global hooks for centralized changes. Cover code with unit tests (Jest) at ≥90% coverage.
- Testing: test critical scenarios, including edge cases (empty collections, missing hooks). Also perform integration testing with a real Payload CMS instance.
- Publication and documentation: prepare a README with usage examples, compile TypeScript to dist, and publish to npm. The entire process takes from 3 to 10 days depending on complexity.
What's Included in the Work
- Source code of the plugin in TypeScript with full typing.
- Unit tests (Jest) with ≥90% coverage.
- Documentation (README) with configuration examples and usage.
- Post-deployment support: fixes and adjustments for one month.
Common Mistakes When Developing Plugins
- Not checking that collections and hooks may be undefined or empty — causes runtime errors.
- Using the afterInit hook to add fields instead of modifying collections directly — fields can't be applied after initialization.
- Forgetting to export plugin configuration types — users lose autocomplete in their IDE.
When to Order a Plugin?
Each of our plugins is tested and documented. We find optimal architectural solutions, considering the specifics of your project. A plugin pays for itself within a few months of use — time savings on adding repetitive fields can reach 40%. If you want a ready-made solution with quality guarantees, order plugin development — contact us to discuss your task.