Plugins

Payload comes with a built-in Plugins infrastructure that allows developers to build their own modular and easily reusable sets of functionality.

Writing plugins is no more complex than writing regular JavaScript. If you know how spread syntax works and are up to speed with Payload concepts, writing a plugin will be a breeze.

Example use cases:

  • Automatically sync data from a specific collection to HubSpot or a similar CRM when data is added or changes
  • Add password-protection functionality to certain documents
  • Add a full e-commerce backend to any Payload app
  • Add custom reporting views to Payload's admin panel
  • Encrypt specific collections' data
  • Add a full form builder implementation
  • Integrate all upload-enabled collections with a third-party file host like S3 or Cloudinary
  • Add custom endpoints or GraphQL queries / mutations with any type of custom functionality that you can think of

How to install plugins

The base Payload config allows for a plugins property which takes an array of Plugins.

1
import { buildConfig } from 'payload/config'
2
// note: these plugins are not real (yet?)
3
import addLastModified from 'payload-add-last-modified'
4
import passwordProtect from 'payload-password-protect'
5
import { mongooseAdapter } from '@payloadcms/db-mongodb'
6
import { postgresAdapter } from '@payloadcms/db-postgres'
7
8
import { viteBundler } from '@payloadcms/bundler-vite'
9
import { webpackBundler } from '@payloadcms/bundler-webpack'
10
11
12
const config = buildConfig({
13
bundler: webpackBundler() // or viteBundler(),
14
collections: [
15
{
16
slug: 'pages',
17
fields: [
18
{
19
name: 'title',
20
type: 'text',
21
required: true,
22
},
23
{
24
name: 'content',
25
type: 'richText',
26
required: true,
27
},
28
],
29
},
30
],
31
db: mongooseAdapter({}) // or postgresAdapter({})
32
plugins: [
33
// Many plugins require options to be passed.
34
// In the following example, we call the function
35
// and pass it options accordingly
36
passwordProtect(['pages']),
37
38
// This plugin takes no options and just
39
// needs to be passed directly
40
addLastModified,
41
42
// ..
43
// To understand how to use the plugins you're interested in,
44
// consult their corresponding documentation
45
],
46
})
47
48
export default config

When Plugins are initialized

Payload Plugins are executed after the incoming config is validated, but before it is sanitized and had default options merged in.

After all plugins are executed, the full config with all plugins will be sanitized.

Simple example

Here is an example for how to automatically add a lastModifiedBy field to all Payload collections using a Plugin written in TypeScript.

1
import { Config, Plugin } from 'payload/config'
2
3
const addLastModified: Plugin = (incomingConfig: Config): Config => {
4
// Find all incoming auth-enabled collections
5
// so we can create a lastModifiedBy relationship field
6
// to all auth collections
7
const authEnabledCollections = incomingConfig.collections.filter((collection) =>
8
Boolean(collection.auth),
9
)
10
11
// Spread the existing config
12
const config: Config = {
13
...incomingConfig,
14
collections: incomingConfig.collections.map((collection) => {
15
// Spread each item that we are modifying,
16
// and add our new field - complete with
17
// hooks and proper admin UI config
18
return {
19
...collection,
20
fields: [
21
...collection.fields,
22
{
23
name: 'lastModifiedBy',
24
type: 'relationship',
25
relationTo: authEnabledCollections.map(({ slug }) => slug),
26
hooks: {
27
beforeChange: [
28
({ req }) => ({
29
value: req?.user?.id,
30
relationTo: req?.user?.collection,
31
}),
32
],
33
},
34
admin: {
35
position: 'sidebar',
36
readOnly: true,
37
},
38
},
39
],
40
}
41
}),
42
}
43
44
return config
45
}
46
47
export default addLastModified

Available Plugins

You can discover existing plugins by browsing the payload-plugin topic on GitHub.

For maintainers building plugins for others to use, please add the topic to help others find it. If you would like one to be built by the core Payload team, open a Feature Request in our GitHub Discussions board. We would be happy to review your code and maybe feature you and your plugin where appropriate.

Next

Form Builder Plugin