Payload AI Plugin

🌟 Supercharge Your Payload CMS with AI-Powered Content Creation

The Payload AI Plugin is an advanced extension that integrates modern AI capabilities into your Payload CMS, streamlining content creation and management.

⚠️ Important: This plugin is in active development. We're doing our best to improve its features and functionality. Please be prepared for regular updates; The plugin has been tested with a Payload version v3.38.0.

To give it a try, we recommend using Payload's website template.

🎥 Watch the Magic in Action

Want to dive deeper?

🎥 Explore More in Our Extended Demo

⚙️ Guide to Personalize

✨ Supported Fields and Features

Text and RichText Field

• 📝 Text Generation
  • [x] Compose masterpieces effortlessly
  • [x] Proofread with precision (Beta)
  • [x] Translate across languages
  • [ ] Expand your ideas
  • [ ] Summarize with clarity
  • [ ] Simplify complex concepts
  • [x] Rephrase for maximum impact (Beta)

Upload Field

• 🎙️ Voice Generation powered by ElevenLabs, OpenAI
• 🖼️ Image Generation powered by OpenAI
  • Now also supports GPT-Image-1 Model

Other Features

• 🔌 Bring Your Own Model (Setup guide)
• 🎛️ Field-level Prompt Customization
• 🔐 Access Control Support
• 🧠 Prompt Editor
• 🌍 Internationalization Support
• 📊 Document Analyzer (Coming Soon)
• ✅ Fact Checking (Coming Soon)
• 🔄 Automated Content Workflows (Coming Soon)
• 🌍 Editor AI suggestions (Coming Soon)
• 💬 AI Chat Support (Coming Soon)

📚 Table of Contents

• Installation
• Usage
• Configuration
• Setup Guide
• Contributing

📦 Installation

After PayloadCMS has been installed, run this command:

pnpm add @ai-stack/payloadcms

🛠 Usage

Add below in src/payload.config.ts

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

export default buildConfig({
  plugins: [
    payloadAiPlugin({
      collections: {
        [Posts.slug]: true,
      },
      debugging: false,
    }),
  ],
  // ... your existing Payload configuration
})

Add AI Plugin feature to your richText field:

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

// Add below in the Lexical Editor field config of you Collection or Plugin (e.g. src/collections/Posts/index.ts)
fields: [
  {
    name: 'content',
    type: 'richText',
    editor: lexicalEditor({
      features: ({ rootFeatures }) => {
        return [
          // ... your existing features
          HeadingFeature({ enabledHeadingSizes: ['h1', 'h2', 'h3', 'h4'] }),

          // Please add below
          PayloadAiPluginLexicalEditorFeature(),
        ]
      },
    }),
  },
]

⚙️ Configuration

To get started, set your API keys in a .env file in your project root:

# Required for text and image generation
OPENAI_API_KEY=your-openai-api-key

# Required if using gpt-image-1 model
OPENAI_ORG_ID=your-org-id

# Optional: Other supported providers
ANTHROPIC_API_KEY=your-anthropic-api-key
GOOGLE_GENERATIVE_AI_API_KEY=your-google-api-key
ELEVENLABS_API_KEY=your-elevenlabs-api-key

# Optional: Custom OpenAI Endpoint
OPENAI_BASE_URL=https://api.openai.com/v1

⚠️ Important: Restart your server after updating .env or plugin settings to apply the changes. Also, you might want to run payload generate:importmap to regenerate the import map before starting the server.

👇 Advanced Configuration

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

export default buildConfig({
  plugins: [
    payloadAiPlugin({
      collections: {
        [Posts.slug]: true,
      },

      // Optional
      globals: {
        [Home.slug]: true,
      },

      // Optional: Show debug logs to list AI-enabled fields
      debugging: false,

      // Optional: Disable sponsor message in the console
      disableSponsorMessage: false,

      // Optional: Pre-generate prompts on server start (recommended for dev only)
      generatePromptOnInit: process.env.NODE_ENV !== 'production',

      // Optional: Specify the media collection used by the gpt-image-1 model to reference images (defaults to media)
      uploadCollectionSlug: "media",

      // Optional: Access control for AI features
      access: {
        // Control who can generate AI content
        generate: ({ req }) => req.user?.role === 'admin',
        
        // Control who can modify AI settings and prompts
        settings: ({ req }) => req.user?.role === 'admin',
      },

      options: {
        // Visit locale-codes for tags, 
        // defaults to display all language options for Translate feature
        // https://www.npmjs.com/package/locale-codes
        enabledLanguages: ["en-US", "zh-SG", "zh-CN", "en"],
      },

      // Optional: Additional fields that can be referenced in prompts
      promptFields: [
        // Expose "url" field on images collection
        {
          name: 'url',
          collections: ['images'],
        },
        // Expose custom async function that generates markdown summary of any document
        {
          name: 'markdown',
          async getter(doc, {collection}) => docToMarkdown(collection, doc)
        }
      ],

      // Optional: Control how field prompts are seeded for the first time
      seedPrompts: ({path}) => {
        if (path.endsWith('.meta.description')) {
          return {
            data: {
              prompt: 'Generate SEO-friendly title for this document: {{markdown}}',
              // other instruction options
            }
          }
        }
        // Don't allow generating slugs
        if (path.endswith('.slug')) return false
        // returning undefined fallbacks to default seed prompt
      },

      // Optional: Custom media upload handling, useful for multi-tenant setups
      mediaUpload: async (result, { request, collection }) => {
        return request.payload.create({
          collection,
          data: result.data,
          file: result.file,
        })
      },
    }),
  ],
})

OpenAI Endpoint

If you want to use a custom endpoint for the OpenAI provider, set your base URL like this:

OPENAI_BASE_URL=https://api.openai.com/v1

If not specified, the default OpenAI endpoint will be used.

For detailed guidance on personalizing and configuring the plugin to match your needs, check out the Complete Guide. It walks you through every step, from setting up fields to generating amazing content!

Enabling AI for Custom Components

⚠️ Note: Custom fields don't fully adhere to the Payload schema, making it difficult to determine which components support injecting ComposeField as a Description. If AI enabled fields don't display Compose settings, manually add the following component path:

@ai-stack/payloadcms/fields#ComposeField

To view AI enabled fields, enable the debugging flag in your plugin config or check your server startup logs.

🤝 Support Development

I build and maintain this in my free time because I love seeing the community benefit from it. Keeping it alive takes real hours and real money (those AI credits aren’t free 😄).

If this project has saved you time or made your work easier, why not fuel my next coding session with a coffee?

Any support means the world to me. Thank you for even considering it!

👥 Contributing

Innovators: welcome! We're always excited to expand our community and hear fresh ideas. Whether you’re here to share feedback, suggest features, or contribute code, we’d love to have you on board.

Feel free to create a pull request with your ideas, improvements, or bug fixes. No contribution is too small, and every bit helps us grow!

Join the conversation on Payload's Discord and let’s build something amazing together! 🚀✨

Local development

This repo includes a minimal Payload app under dev to iterate on the plugin quickly.

Prerequisites

• Node.js (see .nvmrc) and pnpm
• A database connection string for DATABASE_URI (Postgres or Mongo)
• Optional: AI provider keys to test features (OPENAI_API_KEY, ANTHROPIC_API_KEY, GOOGLE_GENERATIVE_AI_API_KEY, ELEVENLABS_API_KEY)

1. Install dependencies

pnpm install

2. Set up the dev app environment

cp dev/.env.example dev/.env
# Edit dev/.env:
# - Set DATABASE_URI to your DB connection string
# - Set PAYLOAD_SECRET to a strong random string
# - Optionally set AI provider keys to exercise features

3. Start the dev app (admin available at http://localhost:3000)

pnpm dev

If you run into admin import-map issues, regenerate it:

pnpm generate:importmap

Optionally regenerate Payload types:

pnpm generate:types

4. Develop

• Plugin source lives in src/; the dev app imports it locally.
• Edit files in src/** and refresh the dev app to validate changes.

5. Tests, linting, formatting

pnpm test           # runs Vitest + Playwright (see dev/int.spec.ts, dev/e2e.spec.ts)
pnpm lint           # ESLint
pnpm prettier --write .   # Prettier (format all files)

6. Build the plugin

pnpm build

7. Try the built package in another Payload project (optional)

pnpm pack  # creates a tarball in the repo root
# then in your other project:
pnpm add /path/to/ai-plugin-*.tgz

Project structure quick reference

• src/ — plugin source code
• dev/ — minimal Payload app wired to this plugin for local testing
• Tests — see dev/int.spec.ts and dev/e2e.spec.ts for integration and e2e tests