Redirects Plugin - Payload

This plugin allows you to easily manage redirects for your application from within your Admin Panel. It does so by adding a redirects collection to your config that allows you specify a redirect from one URL to another. Your front-end application can use this data to automatically redirect users to the correct page using proper HTTP status codes. This is useful for SEO, indexing, and search engine ranking when re-platforming or when changing your URL structure.

For example, if you have a page at /about and you want to change it to /about-us, you can create a redirect from the old page to the new one, then you can use this data to write HTTP redirects into your front-end application. This will ensure that users are redirected to the correct page without penalty because search engines are notified of the change at the request level. This is a very lightweight plugin that will allow you to integrate managed redirects for any front-end framework.

<Banner type="info"> This plugin is completely open-source and the [source code can be found here](https://github.com/payloadcms/payload/tree/3.x/packages/plugin-redirects). If you need help, check out our [Community Help](https://payloadcms.com/community-help). If you think you've found a bug, please [open a new issue](https://github.com/payloadcms/payload/issues/new?assignees=&labels=plugin%3A%redirects&template=bug_report.md&title=plugin-redirects%3A) with as much detail as possible. </Banner>

Core features

Adds a redirects collection to your config that:
- includes a from and to fields
- allows to to be a document reference

Installation

Install the plugin using any JavaScript package manager like pnpm, npm, or Yarn:

bash

  pnpm add @payloadcms/plugin-redirects

Basic Usage

In the plugins array of your Payload Config, call the plugin with options:

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

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

export default config

Options

Option	Type	Description
`collections`	`string[]`	An array of collection slugs to populate in the `to` field of each redirect.
`overrides`	`object`	A partial collection config that allows you to override anything on the `redirects` collection.
`redirectTypes`	`string[]`	Provide an array of redirects if you want to provide options for the type of redirects to be supported.
`redirectTypeFieldOverride`	`Field`	A partial Field config that allows you to override the Redirect Type field if enabled above.

Note that the fields in overrides take a function that receives the default fields and returns an array of fields. This allows you to add fields to the collection.

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

Frontend Integration

It's important to note that this plugin only manages the redirects within the Payload Admin Panel and database. It does not handle the redirect itself.

You will need to implement the actual redirect logic in your front-end application (e.g., Next.js, Express, etc.) by querying the redirects collection and handling the redirects based on your application's routing logic.

A good example of how to implement this can be found in the Website Template.

TypeScript

All types can be directly imported:

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

Examples

The Templates Directory also contains an official Website Template and E-commerce Template, both of which use this plugin.