Redirects Plugin

Lightweight Payload plugin that adds a managed redirects collection to the Admin Panel. Useful for SEO-safe URL migrations when re-platforming or restructuring URL hierarchies.

What It Does

Adds a redirects collection with from (old URL) and to (new URL / document reference) fields
Stores redirect data in the database — does not handle the actual HTTP redirect itself
Frontend app must query the collection and apply redirects (e.g. Next.js redirects() or middleware)

Installation

pnpm add @payloadcms/plugin-redirects

import { buildConfig } from 'payload'
import { redirectsPlugin } from '@payloadcms/plugin-redirects'

const config = buildConfig({
  collections: [{ slug: 'pages', fields: [] }],
  plugins: [
    redirectsPlugin({
      collections: ['pages'],
    }),
  ],
})

Options

Option	Type	Description
`collections`	`string[]`	Collection slugs available as document targets in the `to` field
`overrides`	`object`	Partial collection config — override anything on the `redirects` collection
`redirectTypes`	`string[]`	Enable redirect type selection (e.g. `['301', '302']`)
`redirectTypeFieldOverride`	`Field`	Override the redirect type field config

Adding Custom Fields via Overrides

redirectsPlugin({
  collections: ['pages'],
  overrides: {
    fields: ({ defaultFields }) => [
      ...defaultFields,
      { type: 'text', name: 'customField' },
    ],
  },
  redirectTypes: ['301', '302'],
  redirectTypeFieldOverride: {
    label: 'Redirect Type (Overridden)',
  },
})

Frontend Integration

The plugin only stores data — your frontend handles the actual redirect:

Next.js App Router: read the redirects collection in next.config.js redirects() or in middleware
Next.js middleware pattern: query Payload REST API, match req.nextUrl.pathname against from fields, then NextResponse.redirect()
Reference implementation: Website Template

TypeScript

import { PluginConfig } from '@payloadcms/plugin-redirects/types'

Key Takeaways

Plugin stores, frontend redirects — the plugin manages redirect records; HTTP redirect logic is your responsibility
to field supports document references — link to Payload documents (pages, posts) not just raw URLs; prevents dead links after slug changes
Use redirectTypes for 301/302 control — important for SEO: 301 = permanent (passes link equity), 302 = temporary
overrides.fields receives defaultFields — always spread defaultFields when adding custom fields to avoid losing from/to
Official templates include full examples — Website Template and E-commerce Template both implement the full Next.js integration pattern

wiki/payloadcms/plugins — all 10 official Payload plugins
wiki/payloadcms/plugin-nested-docs — parent/child URL hierarchies (combine with redirects for slug-change workflows)
wiki/payloadcms/plugin-form-builder — another lightweight official plugin pattern
wiki/payloadcms/rest-api — query redirects collection from frontend middleware

Sources

raw/plugins__redirects.md — Payload CMS official docs

3.6 KiB Raw Permalink Blame History