vault backup: 2026-05-15 16:22:51

wiki/payloadcms/plugin-redirects.md

@@ -0,0 +1,98 @@
+---
+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