@dudefactory/payload-plugin-seo-diagnostics

A Payload CMS plugin that provides SEO content auditing and diagnostics across your collections.

Features

• 🔍 SEO Audit Dashboard - Review SEO titles, descriptions, and images across all localized collections
• 🌍 Multi-locale Support - Check content quality across English, Spanish, and custom locales
• ✅ Configurable Rules - Set custom character limits and validation rules
• 🎯 Quick Navigation - Click to edit documents directly from the diagnostics view
• 📊 Issue Summary - See how many documents need SEO improvements at a glance

Installation

pnpm add @dudefactory/payload-plugin-seo-diagnostics

Usage

Basic Setup

// payload.config.ts
import { seoDiagnosticsPlugin } from '@dudefactory/payload-plugin-seo-diagnostics';

export default buildConfig({
  plugins: [seoDiagnosticsPlugin()],
});

Custom Configuration

import { seoDiagnosticsPlugin } from '@dudefactory/payload-plugin-seo-diagnostics';

export default buildConfig({
  plugins: [
    seoDiagnosticsPlugin({
      // Audit these collections
      collections: [
        {
          slug: 'pages',
          label: 'Pages',
          docLabelPaths: ['title', 'slug'],
          metaPath: 'meta',
        },
        {
          slug: 'posts',
          label: 'Posts',
          docLabelPaths: ['title', 'slug'],
          metaPath: 'meta',
        },
      ],

      // SEO title character limit
      titleCharacterLimit: 60,

      // SEO description character range
      descriptionCharacterRange: {
        min: 100,
        max: 150,
      },

      // Custom locale validation rules
      localeValidationRules: [
        {
          localeCode: 'en',
          forbiddenCharacterPatterns: [
            { name: 'Spanish', pattern: '[áéíóúÁÉÍÓÚñÑüÜ¡¿]' },
          ],
        },
        {
          localeCode: 'es',
          forbiddenCharacterPatterns: [
            { name: 'English slang', pattern: 'ing\\b' },
          ],
        },
        {
          localeCode: 'fr',
          forbiddenCharacterPatterns: [
            { name: 'Accented non-French', pattern: '[ñ]' },
          ],
        },
      ],
    }),
  ],
});

Configuration Options

collections

Array of collections to audit for SEO issues.

• Type: SeoDiagnosticsCollectionConfig[]
• Default: ['pages', 'posts', 'services']

SeoDiagnosticsCollectionConfig

• slug (string) - Collection slug
• label (string) - Collection display name
• docLabelPaths (string[], optional) - Paths to use for document labels (e.g., ['title', 'slug'])
• metaPath (string, optional) - Path to SEO metadata (default: 'meta')

titleCharacterLimit

Maximum allowed characters for SEO titles.

• Type: number
• Default: 60

descriptionCharacterRange

Recommended character range for SEO descriptions.

• Type: { min: number; max: number }
• Default: { min: 100, max: 150 }

validateSpanishCharacters (Deprecated)

Enable Spanish character validation. Deprecated — use localeValidationRules instead.

• Type: boolean
• Default: true

localeValidationRules

Custom character validation rules per locale. Allows you to validate any character patterns for any locale combination.

• Type: LocaleValidationRule[]
• Default: Uses Spanish validation for English locales (if validateSpanishCharacters is true)

LocaleValidationRule

{
  // Locale code prefix to match (e.g., 'en' matches 'en-US', 'en-GB')
  localeCode: string;

  // Character patterns forbidden in this locale
  forbiddenCharacterPatterns?: LocaleCharacterPattern[];
}

LocaleCharacterPattern

{
  // Name of the character set
  name: string;

  // Regex pattern for forbidden characters
  pattern: string; // e.g., '[áéíóúÁÉÍÓÚñÑüÜ¡¿]'
}

Examples

Disable all character validation:

localeValidationRules: [];

Check English for Spanish and French characters:

localeValidationRules: [
  {
    localeCode: 'en',
    forbiddenCharacterPatterns: [
      { name: 'Spanish', pattern: '[áéíóúÁÉÍÓÚñÑüÜ¡¿]' },
      { name: 'French', pattern: '[àâäçèéêëîïôöùûüœæ]' },
    ],
  },
];

Check Spanish for non-Spanish characters:

localeValidationRules: [
  {
    localeCode: 'es',
    forbiddenCharacterPatterns: [
      { name: 'English slang endings', pattern: 'ing\\b' },
      { name: 'German umlauts', pattern: '[äöüß]' },
    ],
  },
];

Accessing the View

After installation, a SEO Diagnostics link appears in your Payload admin navigation. Click it to access the audit dashboard.

Path: /admin/seo-diagnostics

Issue Detection

The plugin automatically flags:

• ✋ Missing SEO title or description
• 📏 SEO title exceeds character limit
• 📝 SEO description too short or too long
• 🌐 Mismatched locale characters (e.g., Spanish characters in English content)

Monorepo Usage

If using this in a monorepo with local plugins:

{
  "dependencies": {
    "@dudefactory/payload-plugin-seo-diagnostics": "workspace:*"
  }
}

License

MIT