@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

Full documentation →

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.

For configuration options, tree view features, URL history, organization scoping, extensibility, and more, see the full documentation.

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 — every operation the endpoints perform runs with overrideAccess: false as the requesting user, so the access rules on your page and folder collections are always enforced.

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