Payload | Plugin documentation

[JeffreyArts]

Plugins - Overview

On the plugins overview page, I read "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."

This got me excited to start writing my first plugin, since my understanding of Payload concepts is little, I wanted to start with copying the plugin code as its provided on this page at the simple plugin section.

import { Config, Plugin } from 'payload/config'

const addLastModified: Plugin = (incomingConfig: Config): Config => {
  // Find all incoming auth-enabled collections
  // so we can create a lastModifiedBy relationship field
  // to all auth collections
  const authEnabledCollections = incomingConfig.collections.filter((collection) =>
    Boolean(collection.auth),
  )

  // Spread the existing config
  const config: Config = {
    ...incomingConfig,
    collections: incomingConfig.collections.map((collection) => {
      // Spread each item that we are modifying,
      // and add our new field - complete with
      // hooks and proper admin UI config
      return {
        ...collection,
        fields: [
          ...collection.fields,
          {
            name: 'lastModifiedBy',
            type: 'relationship',
            relationTo: authEnabledCollections.map(({ slug }) => slug),
            hooks: {
              beforeChange: [
                ({ req }) => ({
                  value: req?.user?.id,
                  relationTo: req?.user?.collection,
                }),
              ],
            },
            admin: {
              position: 'sidebar',
              readOnly: true,
            },
          },
        ],
      }
    }),
  }

  return config
}

export default addLastModified

I copied this code into its own file, imported it in my payload.config.ts file, and added it to my buildConfig options object as a parameter in the plugins array. When I try this sample code, I immediately get an error message: "incomingConfig.collections.filter((collection)", okay that makes kinda sense... I haven't provided a configuration object in my plugins declaration.

So I removed the whole "collections" declaration in the plugin's config. Which resulted in the error "plugin is not a function", weird... So I tried to add a collections array with 1 collection to the options of this test plugin, which threw me a different error (I was providing the slug string of the collection instead of the collection object) and for the sake of this problem definition I'll stop explaining my bugfixing proces cause I believe the point has been clear by now.

Desired solution

While a tutorial on developing your first plugin would be desirable, updating the existing documentation with the following features would already be of great value.

1. Provide a demo plugin that works straight away It doesn't have to do anything fancy, console.log something on whatever action/event would already be good enough. My motivation for developing a plug-in is to add an extra config field on a collection. Since the goal of this section of the documentation (in my opinion) is to provide an out-of-the-box (working) demo plugin. I think something as simple as adding a configuration option "sparkle" on a collection level, that would accept a boolean to display a ✨ emoji in front of the collection title in the admin would already be an amazing start to explore creating a payload plugin, while also teasing me a little bit with some of the possibilities within Payload's concepts

2. Modify the intro section

"(...) If you know how spread syntax works and are up to speed with Payload concepts (..)" If you are familair with Payload concepts, I expect you are most likely also familair with spread operators. I'd rather see a hyperlink that leads to a page that goes in deep detail on Payload concepts as spread operators. Obviously it doesn't hurt to display both. That said, the existing concepts page is insufficient for this, since this page doesn't make it clear to me how Payload's concept work on a technical level. I know that these concepts exists and what they do, I just don't know how to modify them via a plugin.

[JeffreyArts]

Totally missed this one.... https://payloadcms.com/docs/plugins/build-your-own

[jmikrut]

Good find! Yes, we have some materials regarding plugin creation but plan to make a lot more as well.

Keep an eye out - more is on the way!

[github-actions[bot]]

This issue has been automatically locked. Please open a new issue if this issue persists with any additional detail.