@delmaredigital/payload-page-tree

A Payload CMS plugin that extends the built-in folders feature to auto-generate hierarchical URL slugs. Folders define URL structure, pages pick a folder, and slugs are auto-generated.

Documentation: plugins.delmaredigital.com/docs/page-tree · Overview

Installation

pnpm add @delmaredigital/payload-page-tree

Quick Start

1. Add the plugin

// 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
  ],
})

2. Define your collection

Your collections must have a slug field. The plugin makes it read-only and auto-generates values from folder path + page segment.

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

export const Pages: CollectionConfig = {
  slug: 'pages',
  fields: [
    { name: 'title', type: 'text', required: true },
    {
      name: 'slug',
      type: 'text',
      required: true,
      unique: true,
      index: true,
    },
  ],
}

Important: Do NOT use Payload's slugField() helper. Use a plain text field — the plugin manages slugs via its own hooks.

3. Frontend routing

// 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,
  })

  // ...
}

That's it! The plugin adds folder, pageSegment, sortOrder, and slugHistory fields automatically, and registers the tree view at /admin/page-tree.

Access control

The tree view calls fourteen endpoints under /api/page-tree/*. Two layers decide who may use them:

1. Endpoint gate — the access option runs before every endpoint. By default it requires an authenticated Payload user (401 without a user, 403 when denied).
2. Collection access rules — reads and writes on the documents a user operates on run with overrideAccess: false as the requesting user, so the access rules on your page and folder collections are enforced. URL maintenance (slug ancestry, collision checks, cascade inventories) reads with trusted access, but only beneath folders the user can read. See access control for the details.

pageTreePlugin({
  // Only admins may use the tree endpoints
  access: ({ req }) => req.user?.role === 'admin',
})

Upgrading from 0.3.16 or earlier: those versions registered the endpoints with no authentication and bypassed collection access rules. Upgrade, and review the access rules on your page and folder collections — they now govern the tree. See the CHANGELOG.

License

MIT