---
title: "Redirects Plugin"
aliases: [payload-redirects, plugin-redirects, redirects-collection]
tags: [payloadcms, plugin, seo, redirects, cms]
sources: [raw/plugins__redirects.md]
created: 2026-05-15
updated: 2026-05-15
---

# 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

```bash
pnpm add @payloadcms/plugin-redirects
```

```ts
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

```ts
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](https://github.com/payloadcms/payload/tree/main/templates/website)

## TypeScript

```ts
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

## Related Articles

- [[wiki/payloadcms/plugins|Plugins Overview + Official]] — all 10 official Payload plugins
- [[wiki/payloadcms/plugin-nested-docs|Nested Docs Plugin]] — parent/child URL hierarchies (combine with redirects for slug-change workflows)
- [[wiki/payloadcms/plugin-form-builder|Form Builder Plugin]] — another lightweight official plugin pattern
- [[wiki/payloadcms/rest-api|REST API]] — query `redirects` collection from frontend middleware

## Sources

- `raw/plugins__redirects.md` — Payload CMS official docs