Payload AI Plugin

A Payload plugin is a function that receives plugin-specific options and the existing Payload configuration, then returns a modified configuration.

During the Payload startup process, the initialization follows this order:

1. Incoming config is validated
2. Plugins execute
3. Default options are integrated
4. Sanitization cleans and validates data
5. Final config gets initialized

Install the @ai-stack/payloadcms package using pnpm to add AI capabilities to your Payload CMS project.

pnpm add @ai-stack/payloadcms

To initialize the plugin, add payloadAiPlugin to the plugins array in your src/payload.config.ts. You must specify which collections (or globals) should have AI features enabled via the collections or globals configuration objects.

import { payloadAiPlugin } from '@ai-stack/payloadcms'

export default buildConfig({
  plugins: [
    payloadAiPlugin({
      collections: {
        [Posts.slug]: true,
      },
      debugging: false,
    }),
  ],
  // ... rest of your config
})

To use a plugin in a Payload project, import the plugin function and add it to the plugins array within your payload.config(). You can pass an options object to the plugin to configure its behavior.

import myPlugin from 'my-plugin'

export const config = buildConfig({
  plugins: [
    // You can pass options to the plugin
    myPlugin({
      enabled: true,
    }),
  ],
})

The Title Field serves as the foundation for other AI-generated fields. Users should input an initial phrase or idea, which the AI then uses to suggest or refine a title.

Workflow:

1. Enter a phrase (e.g., "A funny blog title") in the Title Field.
2. Click the Compose button.
3. Use the Title Menu to perform actions like proofreading, rephrasing, or translating.
4. Configure Title Settings to define how the AI generates or refines titles using template strings like "Suggest a title based on {{ title }}".

# No specific code snippet provided for UI interaction, but template syntax is: 
"Suggest a title based on {{ title }}"

The Banner Field generates visual content based on the Title Field.

Important: Always ensure the Title Field is populated before working on the Banner, otherwise results may be random or fail.

Configuration: Use Banner Settings to define the AI's behavior and tone. You can use dynamic fields in your instructions.

Example Setting: "You are a professional designer. Create a visually appealing banner for {{ title }}."

The Content Field is used for generating blog posts or articles. It relies on the Title Field for context.

Key Configuration Tabs:

1. Prompt Tab: Add specific prompts using schema fields.

   • Example: "Write a blog on: {{ title }}" or "This post is about {{ title }}. Features include {{ featureA }}".

2. System Prompt Tab: Define the AI's persona and tone.

   • Example: "INSTRUCTIONS: You are a professional blog writer. Craft captivating and well-organized articles."

3. Layout Tab: Defines the structural organization of the content (headings, lists, paragraphs).

Note: The System Prompt and Layout tabs are exclusive to richText fields.

The template uses Vitest for testing. You can write tests in the dev folder (e.g., int.spec.ts) to verify your plugin's behavior. Use describe blocks to group tests and it blocks for individual test cases.

describe('Plugin tests', () => {
  // Create tests to ensure expected behavior from the plugin
  it('some condition that must be met', () => {
   // Write your test logic here
   expect(...)
  })
})

To use AI features like Compose, Proofread, and Translate within a Lexical-based RichText field, import and add PayloadAiPluginLexicalEditorFeature() to your field's editor configuration.

import { PayloadAiPluginLexicalEditorFeature } from '@ai-stack/payloadcms'

fields: [
  {
    name: 'content',
    type: 'richText',
    editor: lexicalEditor({
      features: ({ rootFeatures }) => {
        return [
          HeadingFeature({ enabledHeadingSizes: ['h1', 'h2', 'h3', 'h4'] }),
          // Add this line:
          PayloadAiPluginLexicalEditorFeature(),
        ]
      },
    }),
  },
]

The template includes a dev folder containing a sample Payload project for testing.

1. Navigate to the dev folder.
2. Copy .env.example to .env.
3. Update DATABASE_URI to your database connection string.
4. Update PAYLOAD_SECRET to a unique string.
5. Run pnpm/npm/yarn dev to start the development server at http://localhost:3000.

The Voice Over Field converts text content into audio using OpenAI or ElevenLabs models. This field depends on the Content Field being generated first.

Setup Steps:

1. API Keys: Add OPENAI_API_KEY or ELEVENLABS_API_KEY to your .env file.
2. Prompting: Use the Prompt field to convert content to HTML, as both models support HTML input.
   • Example: "{{ toHTML content }}".
3. Fine-tuning: Use the model-specific settings to adjust voice styles and quality.

When adding new items to existing arrays (like collections or globals) or objects (like hooks), use the JavaScript spread operator (...) to ensure you do not overwrite existing data. Failing to spread existing data can cause conflicts with other plugins or the core Payload configuration.

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

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

// Adding hooks
config.hooks = {
  ...(incomingConfig.hooks || {}),
  // Add additional hooks here
}