Page Tree for Payload CMS

Features

• Minimal config — works with pages and posts collections by default (auto-detects what exists)
• Visual tree view — drag-and-drop reorganization in admin panel
• Auto-generated slugs — hierarchical URLs from folder paths (e.g., /appeals/2024/spring-campaign)
• URL history tracking — automatic audit trail of previous URLs with restore capability
• URL preservation — choose to keep or update URLs when moving content
• Collection switching — dropdown to filter by collection type (when multiple configured)
• Native folders — extends Payload's built-in folders feature
• No dummy pages — folders are purely organizational
• Plugin friendly — works alongside Puck, SEO, and other plugins (see Plugin Order)

Installation

Quick Start

tsCopy// src/payload.config.ts
import { buildConfig } from 'payload'
import { pageTreePlugin } from '@delmaredigital/payload-page-tree'
import { Pages } from './collections/Pages'

export default buildConfig({
  collections: [Pages],
  plugins: [
    pageTreePlugin(),  // Auto-detects 'pages' and 'posts' if they exist
  ],
})

tsCopy// src/collections/Pages/index.ts
import type { CollectionConfig } from 'payload'

export const Pages: CollectionConfig = {
  slug: 'pages',
  fields: [
    { name: 'title', type: 'text', required: true },
    // Define a plain slug field — the plugin will manage it
    {
      name: 'slug',
      type: 'text',
      required: true,
      unique: true,
      index: true,
    },
    // ... other fields
  ],
}

tsCopy// app/[...slug]/page.tsx
export default async function Page({ params }: { params: { slug: string[] } }) {
  const fullSlug = params.slug.join('/')

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

  // ...
}

How It Works

1. Create folders in the Payload admin with a pathSegment (e.g., "appeals", "2024")
2. Nest folders to create hierarchy (e.g., "2024" under "appeals")
3. Create a page and select a folder from the dropdown
4. Slug auto-generates from folder path + page segment (e.g., appeals/2024/spring-campaign)

textCopyFolders:
├── appeals (pathSegment: "appeals")
│   ├── 2024 (pathSegment: "2024")
│   └── 2025 (pathSegment: "2025")
└── services (pathSegment: "services")

Page in "2024" folder with pageSegment "spring-campaign":
→ slug: appeals/2024/spring-campaign
→ URL: /appeals/2024/spring-campaign

Tree View

The plugin adds a visual tree view at /admin/page-tree for managing your page hierarchy:

• Drag-and-drop to reorganize pages and folders (supports multi-select)
• Multi-select support — Cmd/Ctrl+click to select multiple items, then drag or use "Move to..."
• "Move to..." action — right-click menu option to select destination folder without dragging
• Sorting options — sort by name, slug, or status (drag-drop disabled while sorting)
• Collection dropdown — switch between page types (only appears when multiple collections are configured)
• Context menu (right-click) for actions like edit, duplicate, publish/unpublish, move, delete
• URL preservation — when moving folders, choose to keep existing URLs or update them
• Bulk URL updates — "Update All" / "Keep All" buttons for batch confirmation
• Regenerate URLs — manually regenerate slugs for a folder and all its contents
• Visual distinction — folders have subtle background styling to differentiate from pages

Cascading Updates

When you rename a folder's pathSegment or move a folder:

• Keep existing URLs — pages stay at their current URLs (default for moves)
• Update URLs — all pages in that folder (and subfolders) get new slugs based on the new path

This gives you control over URL changes — useful when you want to reorganize content without breaking existing links.

URL History & Redirects

The plugin automatically tracks URL changes for SEO and redirect management.

Automatic History Tracking

Every page has a slugHistory field that records the last 20 URL changes:

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

Changes are tracked automatically when:

• A page is moved to a different folder (reason: move)
• A parent folder is renamed (reason: rename)
• URLs are regenerated via context menu (reason: regenerate)
• A previous URL is restored (reason: restore)

Generating Redirects

Use the redirects endpoint to build redirect maps for your frontend:

tsCopy// Fetch all redirect mappings
const res = await fetch('/api/page-tree/redirects?collection=pages')
const { redirects } = await res.json()

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

tsCopy// middleware.ts
import { NextResponse } from 'next/server'

export async function middleware(request: NextRequest) {
  const res = await fetch(
    `${request.nextUrl.origin}/api/page-tree/redirects?collection=pages`
  )
  const { redirects } = await res.json()

  const redirect = redirects.find(
    r => r.from === request.nextUrl.pathname
  )
  if (redirect) {
    return NextResponse.redirect(
      new URL(redirect.to, request.url), 301
    )
  }
}

Restoring Previous URLs

Right-click a page in the tree view and select "URL History" to view all previous URLs with timestamps and reasons, or restore any previous URL.

Configuration Options

tsCopypageTreePlugin({
  // Collections to add folder-based slugs to (default: ['pages', 'posts'])
  collections: ['pages', 'posts'],

  // Custom folder collection slug (default: 'payload-folders')
  folderSlug: 'payload-folders',

  // Field name for folder path segment (default: 'pathSegment')
  segmentFieldName: 'pathSegment',

  // Field name for page segment (default: 'pageSegment')
  pageSegmentFieldName: 'pageSegment',

  // Disable plugin hooks while preserving schema (default: false)
  disabled: false,

  // Admin view configuration
  adminView: {
    enabled: true,           // Show tree view in admin (default: true)
    path: '/page-tree',      // URL path for tree view (default: '/page-tree')
  },

  // Custom slug builder (replaces default folderPath/pageSegment)
  buildSlug: ({ pageSegment }) => pageSegment,

  // Customize the folders collection (add access control, fields, etc.)
  customizeFolderCollection: (collection) => collection,
})

tsCopypageTreePlugin({
  collections: ['pages', 'articles', 'landing-pages'],
})

Custom Slug Generation

By default, slugs are built as folderPath/pageSegment (e.g., appeals/2024/spring/my-page). The buildSlug callback lets you replace this with any custom logic.

Use Cases

• Flat slugs — Use the tree for content organization without affecting URLs
• Random IDs — URLs that never change regardless of tree structure
• Custom patterns — Collection-aware or locale-based slug schemes

Callback Signature

tsCopytype BuildSlugFn = (args: {
  folderPath: string | null       // e.g., "appeals/2024" or null
  pageSegment: string              // The page's own URL segment
  doc: Record<string, unknown>    // The document data being saved
  operation: 'create' | 'update' // Current operation type
}) => string | Promise<string>

Examples

tsCopypageTreePlugin({
  buildSlug: ({ pageSegment }) => pageSegment,
})

tsCopyimport { nanoid } from 'nanoid'

pageTreePlugin({
  buildSlug: ({ doc, operation }) => {
    // Keep existing slug on update, generate new one on create
    if (operation === 'update' && doc.slug) return doc.slug as string
    return nanoid(21)
  },
})

tsCopypageTreePlugin({
  buildSlug: ({ folderPath, pageSegment }) => {
    if (!folderPath) return pageSegment
    // Take only the last folder segment
    const lastFolder = folderPath.split('/').pop()
    return `${lastFolder}/${pageSegment}`
  },
})

Plugin Order

Why This Matters

The page-tree plugin validates configured collections at initialization. If a collection doesn't exist yet (because another plugin creates it later), page-tree will silently skip it.

tsCopy// CORRECT: Puck creates Pages before page-tree runs
export const plugins = [
  createPuckPlugin({ pagesCollection: 'pages' }),  // Creates Pages collection
  pageTreePlugin({ collections: ['pages'] }),      // Now sees Pages
]

// WRONG: page-tree runs before Pages exists
export const plugins = [
  pageTreePlugin({ collections: ['pages'] }),      // Pages doesn't exist yet!
  createPuckPlugin({ pagesCollection: 'pages' }),  // Creates Pages too late
]

tsCopy// Collections defined in config — order doesn't matter
export default buildConfig({
  collections: [Pages, Posts],  // Both exist before any plugin runs
  plugins: [
    pageTreePlugin({ collections: ['pages', 'posts'] }),
    createPuckPlugin({
      pagesCollection: 'pages',
      autoGenerateCollection: false,
    }),
  ],
})

Organization Scoping

For multi-tenant apps where each organization has isolated content, use customizeFolderCollection to add organization-based access control to folders:

tsCopyimport { pageTreePlugin } from '@delmaredigital/payload-page-tree'
import { orgScopedAccess, createOrganizationField } from './access/organization'

pageTreePlugin({
  collections: ['pages'],
  customizeFolderCollection: (collection) => ({
    ...collection,
    access: orgScopedAccess,
    fields: [...collection.fields, createOrganizationField()],
  }),
})

This ensures:

• Folders are filtered by the user's active organization in the tree view
• New folders are automatically assigned to the user's organization
• Users can only see and manage folders belonging to their organization

Extensibility

Theming Outside Payload Admin

The tree components use Payload's CSS variables for theming. When using components outside the admin panel, import the default theme:

tsCopyimport '@delmaredigital/payload-page-tree/theme.css'

cssCopy.page-tree-wrapper {
  --theme-bg: hsl(var(--background));
  --theme-input-bg: hsl(var(--background));
  --theme-elevation-0: hsl(var(--background));
  --theme-elevation-50: hsl(var(--muted));
  --theme-elevation-100: hsl(var(--border));
  --theme-elevation-150: hsl(var(--border));
  --theme-elevation-400: hsl(var(--muted-foreground));
  --theme-elevation-500: hsl(var(--muted-foreground));
  --theme-elevation-600: hsl(var(--foreground));
  --theme-elevation-700: hsl(var(--foreground));
  --theme-elevation-800: hsl(var(--foreground));
  --theme-success-500: hsl(var(--primary));
  --theme-error-500: hsl(var(--destructive));
  --theme-error-50: hsl(var(--destructive) / 0.1);
}

Custom Edit URLs

Customize where "Edit" links navigate (useful for visual editors like Puck):

tsCopyimport { PageTreeClient, GetEditUrlFn } from '@delmaredigital/payload-page-tree/client'

const getEditUrl: GetEditUrlFn = (collection, id, adminRoute) => {
  return `${adminRoute}/my-editor/${collection}/${id}`
}

// Pass to PageTreeClient component
<PageTreeClient getEditUrl={getEditUrl} ... />

Building Custom Tree Views

Use buildTreeStructure to create tree data for custom UIs:

tsCopyimport { buildTreeStructure, TreeNode } from '@delmaredigital/payload-page-tree'

// Fetch folders and pages from Payload
const folders = await payload.find({ collection: 'payload-folders', limit: 0 })
const pages = await payload.find({ collection: 'pages', limit: 0 })

// Build tree structure
const tree: TreeNode[] = buildTreeStructure(
  folders.docs,
  pages.docs.map(p => ({ ...p, _collection: 'pages' })),
  { collections: ['pages'] }
)

Adding to Existing Projects

The plugin safely handles existing content:

1. Existing pages keep their slugs — the plugin only generates slugs for new pages or when explicitly requested
2. No schema conflicts — pathSegment is optional, so existing folders work without modification
3. Migrate when ready — use the "Regenerate URLs" action to update slugs for specific folders