@extravirgin/payload-plugin-redirects

Redirects plugin for Payload CMS.

Compatibility

• Payload: ^3.0.0
• Node.js: ^18.20.2 || >=20.9.0

Install

npm i @extravirgin/payload-plugin-redirects

Usage

Add the plugin in your Payload config:

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

export default buildConfig({
  collections: [
    {
      slug: 'pages',
      fields: [
        {
          name: 'title',
          type: 'text',
          required: true,
          localized: true,
        },
        {
          name: 'slug',
          type: 'text',
          required: true,
          unique: true,
          localized: true,
          index: true,
        },
        {
          name: 'uri',
          type: 'text',
          localized: true,
          admin: {
            readOnly: true,
            description: 'Auto-derived from slug for redirects plugin smoke testing.',
          },
        },
        {
          name: 'parent',
          type: 'relationship',
          relationTo: 'pages',
          admin: {
            description: 'Optional parent page for nested URL paths.',
          },
        },
      ],
    },
  ],
  plugins: [
    redirectsPlugin({
      disabled: false,
      collections: {
        pages: {
          disabled: false,
          deleteRedirectsOnDelete: true,
          nesting: {
            property: 'parent',
            depth: 10,
          },
          resolveFromUri: ({
            affectedDoc,
            currentDocumentMeta,
            lastPublishedVersionMeta,
            locale,
          }) => {
            const newPublishedUri = currentDocumentMeta.uri
            const lastPublishedUri = lastPublishedVersionMeta.uri

            if (!newPublishedUri || !lastPublishedUri || !affectedDoc.uri) {
              return null
            }

            const oldUrl = affectedDoc.uri.replace(newPublishedUri, lastPublishedUri)
            if (!oldUrl) {
              return null
            }

            const localePrefix = locale ? `/${locale}` : ''

            return `${localePrefix}${oldUrl}`
          },
        },
      },
    }),
  ],
})

Local dev/ app

The repository includes a local Payload app in dev/ for smoke testing.

1. Install dependencies:

cd dev
npm install

2. Create env file:

cp .env.example .env

• dev/ defaults to an in-memory MongoDB (mongodb-memory-server) when DATABASE_URL is not set.
• Set DATABASE_URL in .env only if you want to use an external MongoDB instance.

3. Run the app:

npm run dev

4. Open admin: http://localhost:3010/admin

Use seeded credentials from .env:

• Email: DEV_USER_EMAIL (default [email protected])
• Password: DEV_USER_PASSWORD (default test)

Manual smoke test

1. Login with seeded dev credentials.
2. Seeded pages entries are present: home, about, company (parent: about), team (parent: company).
3. Open about and publish an update with slug changed from about to about-updated.
4. Open redirects and verify 6 redirects were created (entry and nested entries in both locales).