URL history and redirects

When a page's slug changes, the plugin records the old one in the page's slugHistory field. Use it to restore a previous URL or to redirect old links to the new address.

History trackingCopy Anchor Link

slugHistory holds the 20 most recent previous URLs, newest first. Older entries are dropped.

{
  "slug": "marketing/about-us",
  "slugHistory": [
    { "slug": "about-us", "changedAt": "2024-01-15T...", "reason": "move" },
    { "slug": "company/about", "changedAt": "2024-06-01T...", "reason": "edit-url" }
  ]
}

Each entry records why the slug changed:

Restoring a previous URLCopy Anchor Link

Right-click a page in the tree and choose URL History to see every previous URL with its time and reason, and restore any of them. Restoring sets the slug directly, removes that entry from the history and records the URL it replaced with reason restore.

RedirectsCopy Anchor Link

The plugin exports getRedirectMap(payload, collection, options?), which turns the history of every page in a collection into a list of { from, to } pairs with leading slashes. Call it on the server and redirect old URLs to their current page:

import { notFound, permanentRedirect } from 'next/navigation'
import { getPayload } from 'payload'
import config from '@payload-config'
import { getRedirectMap } from '@delmaredigital/payload-page-tree'

export default async function Page({ params }: { params: Promise<{ slug: string[] }> }) {
  const { slug } = await params
  const fullSlug = slug.join('/')
  const payload = await getPayload({ config })

  const { docs } = await payload.find({
    collection: 'pages',
    where: { slug: { equals: fullSlug } },
    limit: 1,
  })

  if (!docs[0]) {
    const redirects = await getRedirectMap(payload, 'pages')
    const redirect = redirects.find((r) => r.from === `/${fullSlug}`)
    if (redirect) permanentRedirect(redirect.to)
    notFound()
  }

  // ...render docs[0]
}

getRedirectMap reads every page that has history, so cache its result if your site has many pages. Called without options it reads with full access, which suits middleware and build steps. Pass { req } to apply that request user's read rules, or { overrideAccess: false } to apply your anonymous read rules.

The redirects endpointCopy Anchor Link

The same list is available over HTTP:

const res = await fetch('/api/page-tree/redirects?collection=pages')
const { redirects, count } = await res.json()

// {
//   "redirects": [
//     { "from": "/about-us", "to": "/marketing/about-us" },
//     { "from": "/company/about", "to": "/marketing/about-us" }
//   ],
//   "count": 2
// }

collection is required and must be one of the plugin's configured collections; otherwise the endpoint answers 400.

URL helper endpointsCopy Anchor Link

The Edit URL modal uses two read-only endpoints you can also call directly. Both pass through the same access gate.