npm package: @focus-reactive/payload-plugin-ai-seo
Description: AI-powered SEO meta generation plugin for Payload CMS
Latest version: 0.1.0

# @focus-reactive/payload-plugin-ai-seo

AI-powered SEO meta generation plugin for [Payload CMS](https://payloadcms.com/).

Automatically generates SEO-optimized `title` and `description` meta tags using OpenAI when creating or updating documents.

## Features

- 🤖 AI-powered meta tag generation using OpenAI
- 🎯 Flexible field mapping for any collection structure
- 🌍 Localization support (generates SEO for current locale)
- ⚡ Automatic generation on document create
- 🔧 Highly configurable per collection

## Installation

```bash
npm install @focus-reactive/payload-plugin-ai-seo
# or
pnpm add @focus-reactive/payload-plugin-ai-seo
# or
yarn add @focus-reactive/payload-plugin-ai-seo
```

## Quick Start

```typescript
// payload.config.ts
import { buildConfig } from "payload";
import { aiSeoPlugin } from "@focus-reactive/payload-plugin-ai-seo";

export default buildConfig({
  // ... your config
  plugins: [
    aiSeoPlugin({
      enabled: true,
      apiKey: process.env.OPENAI_API_KEY ?? "",
      collections: ["pages", "posts"],
      seoFields: {
        title: "meta.title",
        description: "meta.description",
      },
      contentFields: ["title", "content"],
      model: "gpt-4o-mini",
    }),
  ],
});
```

## Configuration

### Plugin Options

| Option          | Type                                       | Required | Description                           |
| --------------- | ------------------------------------------ | -------- | ------------------------------------- |
| `enabled`       | `boolean`                                  | Yes      | Enable/disable the plugin             |
| `apiKey`        | `string`                                   | Yes      | OpenAI API key                        |
| `collections`   | `string \| string[] \| CollectionConfig[]` | Yes      | Collections to apply SEO generation   |
| `seoFields`     | `SeoFields`                                | No       | Default field paths for SEO output    |
| `contentFields` | `string[]`                                 | No       | Default fields to analyze for SEO     |
| `model`         | `OpenAIChatModelId`                        | No       | OpenAI model (default: `gpt-4o-mini`) |

### Collection-Specific Configuration

You can configure each collection individually:

```typescript
aiSeoPlugin({
  enabled: true,
  apiKey: process.env.OPENAI_API_KEY ?? "",
  collections: [
    {
      collection: "pages",
      seoFields: {
        title: "meta.title",
        description: "meta.description",
      },
      contentFields: ["title", "hero", "blocks"],
    },
    {
      collection: "posts",
      seoFields: {
        title: "seo.metaTitle",
        description: "seo.metaDesc",
      },
      contentFields: ["title", "excerpt", "content"],
    },
  ],
});
```

### SeoFields Interface

```typescript
interface SeoFields {
  title: string; // Path to title field (e.g., 'meta.title')
  description: string; // Path to description field (e.g., 'meta.description')
}
```

## How It Works

1. When a document is created, the plugin extracts content from specified `contentFields`
2. Content is sent to OpenAI for analysis
3. AI generates SEO-optimized title (≤60 chars) and description (≤160 chars)
4. Generated values are written to the specified `seoFields` paths
5. Only empty fields are filled - existing SEO values are preserved

## Requirements

- Payload CMS 3.0+
- Node.js 18+
- OpenAI API key

## License

MIT