diff --git a/raw/plugins__plugin-api.md b/raw/_processed/plugins__plugin-api.md similarity index 100% rename from raw/plugins__plugin-api.md rename to raw/_processed/plugins__plugin-api.md diff --git a/wiki/payloadcms/plugin-redirects.md b/wiki/payloadcms/plugin-redirects.md new file mode 100644 index 0000000..f41f7dc --- /dev/null +++ b/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