How to Build Your Own Payload Plugin

New Payload Plugin Template
Building your own Payload Plugin just got a whole lot easier – thanks to our new Plugin Template.

To use the plugin template run npx create-payload-app@latest -t plugin -n my-new-plugin directly in your terminal or clone the repo from GitHub.

This new template comes with everything you need to build a full life-cycle plugin:

  • Example files and functions for extending the payload config

  • A local dev environment to develop the plugin

  • Jest test suite with integrated GitHub workflow

The purpose of this template is to help you jumpstart building your own Plugin, while providing all the tools that will support your plugin from development to production.

To get started, all you need is:

  • A basic understanding of Payload 
  • Typescript / JavaScript experience

Plugin Template

In the payload-plugin-template, you will see a common file structure that is used across all plugins:

  1. root folder - general configuration

  2. /src folder - everything related to the plugin

  3. /dev folder - sanitized test project for development


In the root folder, you will see various files that relate to the configuration of the plugin. We set up our environment in a similar manner in Payload core and across other projects, so hopefully these will look familiar:

  •* - This contains instructions on how to use the template. When you are ready, update this to contain instructions on how to use your Plugin.
  • package.json* - Contains necessary scripts and dependencies. Overwrite the metadata in this file to describe your Plugin.
  • .editorconfig - Defines settings to maintain consistent coding styles.
  • .eslintrc.js - Eslint configuration for reporting on problematic patterns.
  • .gitignore - List specific untracked files to omit from Git.
  • .prettierrc.js - Configuration for Prettier code formatting.
  • LICENSE - As part of the open-source community, we ship all plugins with an MIT license but it is not required.
  • tsconfig.json - Configures the compiler options for TypeScript 

* IMPORTANT: You will need to modify these files.


The purpose of the dev folder is to provide a sanitized local Payload project – so you can run and test your plugin while you are actively developing it.  

Do not store any of the plugin functionality in this folder - it is purely an environment to assist you with developing the plugin.

If you’re starting from scratch, you can easily setup a dev environment like this:

mkdir dev
cd dev
npx create-payload-app

If you’re using the plugin template, the dev folder is built out for you and the samplePlugin has already been installed in dev/payload.config().

plugins: [
// when you rename the plugin or add options, make sure to update it here
enabled: false,

You can add to the dev/payload.config and build out the dev project as needed to test your plugin.

When you’re ready to start development, navigate into this folder with cd dev

And then start the project with yarn dev and pull up http://localhost:3000/ in your browser.


Another benefit of the dev folder is that you have the perfect environment established for testing.

A good test suite is essential to ensure quality and stability in your plugin. Payload typically uses Jest; a popular testing framework, widely used for testing JavaScript and particularly for applications built with React. 

Jest organizes tests into test suites and cases. We recommend creating tests based on the expected behavior of your plugin from start to finish. Read more about tests in the Jest documentation.

The plugin template provides a stubbed out test suite at dev/plugin.spec.ts which is ready to go - just add in your own test conditions.

import payload from 'payload'
describe('Plugin tests', () => {
// Example test to check for seeded data
it('seeds data accordingly', async () => {
const newCollectionQuery = await payload.find({
collection: 'newCollection',
sort: 'createdAt',
newCollection =
Seeding data

It is a good habit to seed data for each test, this isolates them and ensures they are repeatable. You can see in the example above how easy this is to do with the local API payload offers.

In the plugin template, you can navigate to dev/src/server.ts and see an example seed function.

if (process.env.PAYLOAD_SEED === 'true') {
await seed(payload)

A sample seed function has been created for you at dev/src/seed – update this file with additional data as needed.

export const seed = async (payload: Payload): Promise<void> => {'Seeding data...')
await payload.create({
collection: 'new-collection',
data: {
title: 'Seeded title',
// Add additional seed data here


Now that we have our environment setup and dev project ready to go - it’s time to build the plugin.


First up, the src/index.ts file - this is where the plugin should be imported from. It is best practice not to build the plugin directly in this file, instead we use this to export the plugin and types from their respective files.


To reiterate, the essence of a payload plugin is simply to extend the payload config - and that is exactly what we are doing in this file.

export const samplePlugin =
(pluginOptions: PluginTypes) =>
// ^ The args you want to expose to people using this plugin
(incomingConfig: Config): Config => {
// ^ This will be plugin users config
let config = { ...incomingConfig }
// do something cool with the config here
return config

First, you need to receive the existing payload config along with any plugin options.

Then set the variable config to be equal to a copy of the existing config.

From here, you can extend the config as you wish. 

Finally, you return the config and that is it!

Spread Syntax

Spread syntax (or the spread operator) is a feature in JavaScript that uses the dot notation (...) to spread elements from arrays, strings, or objects into various contexts. 

We are going to use spread syntax to allow us to add data to existing arrays without losing the existing data. It is crucial to spread the existing data correctly – else this can cause adverse behavior and conflicts with Payload config and other plugins.

Let’s say you want to build a plugin that adds a new collection:

config.collections = [
...(config.collections || []),
// Add additional collections here

First, you need to spread the config.collections to ensure that we don’t lose the existing collections. Then you can add any additional collections, just as you would in a regular payload config.

This same logic is applied to other properties like admin, globals, hooks:

config.globals = [
...(config.globals || []),
// Add additional globals here
config.hooks = {
...(config.hooks || {}),
// Add additional hooks here

Some properties will be slightly different to extend, for instance the onInit property:

config.onInit = async payload => {
if (incomingConfig.onInit) await incomingConfig.onInit(payload)
// Add additional onInit code by using the onInitExtension function
onInitExtension(pluginOptions, payload)

If you wish to add to the onInit, you must include the async/await. We don’t use spread syntax in this case, instead you must await the existing onInit before running additional functionality.

In the template, we have stubbed out a basic onInitExtension file that you can use, if not needed feel free to delete it.


If any of your files use server only packages such as fs, stripe, nodemailer, etc, they will need to be removed from the browser bundle. To do that you can alias the file imports with webpack.

When files are bundled for the browser the import paths are essentially crawled to determine what files to include in the bundle. To prevent the server only files from making it into the bundle, we can alias their import paths to a file that can be included in the browser. This will short-circuit the import path crawling and ensure browser only code is bundled.

Webpack is another part of the payload.config that can be a little more tricky to extend. To help here, the template includes a webpack.ts file which takes care of spreading the existing webpack, so you can just add your new stuff:

config.admin = {
...(config.admin || {}),
// Add your aliases to the helper function below
webpack: extendWebpackConfig(incomingConfig)

If your plugin has options, you should define and provide types for these options in a separate file which gets exported from the main index.ts.

export interface PluginTypes {
* Enable or disable plugin
* @default false
enabled?: boolean

If possible, include JSDoc comments to describe the options and their types. This allows a developer to see details about the options in their editor.

Wrap Up

The Payload plugin template provides a fully fitted plugin environment so you can simply focus on building out your feature and get to coding quicker. You can use the template by running npx create-payload-app@latest -t plugin -n my-new-plugin directly in your terminal or by cloning the template directly from GitHub.

For a full life-cycle plugin, it is essential that best practices are followed and testing is thoroughly considered. With the template, you will be able to build out the existing test suite with everything you need.

To learn more about plugins, checkout the plugin documentation. For more on working with the template and best practices, head over to our new plugin template docs.

If you have any questions or feedback, please feel free to reach out - happy building 👋

Use a multi-tenant app to serve the same application on several different domains
How To Build A Multi-Tenant App With Payload

Cut costs, save time, and ship faster by sharing infrastructure when you setup Payload as a multi-tenant application.

Custom CSS
How to Customize the Look and Feel of Payload with CSS

The Custom CSS feature in Payload extends beyond being a simple customization tool–it’s a pathway to seamlessly integrate your CMS with your brand.

Payload Form Builder Plugin
Create custom forms with the official Form Builder Plugin

Tired of dealing with microservices hell? Implement and create forms with ease using Payload’s free form builder plugin.