Payload PageTree Plugin

A hierarchical page tree plugin for Payload CMS that provides a tree-based navigation interface for managing pages with parent-child relationships.

Features

• Tree-based collection view with expandable/collapsible nodes
• Automatic full path computation based on parent hierarchy
• Support for page groups (folders) and regular pages
• Drag-and-drop functionality for reorganizing pages
• Homepage (index page) designation
• Automatic slug generation from titles
• Child deletion protection
• Sorting within siblings
• REST API endpoints for tree operations

Installation

npm install @arevo/plugin-pagetree
# or
pnpm add @arevo/plugin-pagetree
# or
yarn add @arevo/plugin-pagetree

Basic Usage

Add the plugin to your payload.config.ts:

import { PageTree } from '@arevo/plugin-pagetree'

export default buildConfig({
  plugins: [
    PageTree({
      collections: ['pages'], // Array of collection slugs to enable page tree for
    }),
  ],
})

Configuration

Plugin Options

type PageTreePluginOptions = {
  /** Collections where the page tree replaces the list view */
  collections: string[]
  /** Optional: customize label for the left column */
  treeLabel?: string
  /** Disable the plugin */
  disabled?: boolean
}

Example with Options

import { PageTree } from '@arevo/plugin-pagetree'

export default buildConfig({
  plugins: [
    PageTree({
      collections: ['pages', 'docs'],
      treeLabel: 'Page Navigation',
      disabled: false,
    }),
  ],
})

What It Does

The PageTree plugin automatically enhances your specified collections with:

Fields Added

• fullPath (text): Auto-computed full path from parent + slug
• parent (relationship): Parent page or group (null = root)
• isGroup (checkbox): Marks pages as folders vs leaves
• isIndex (checkbox): Marks a page as the homepage
• sort (number): Order among siblings

Hooks Added

• beforeValidate: Auto-generates slugs from titles if not provided
• beforeChange: Computes full paths and manages sorting
• afterChange: Cascades path changes to all children
• beforeDelete: Prevents deletion of pages with children

API Endpoints

The plugin adds two custom endpoints:

1. GET /api/pagetree/:collection/tree - Returns the full page tree
2. POST /api/pagetree/:collection/move - Moves a page to a new parent/position

Admin UI

The plugin replaces the default list view with a custom tree view that allows:

• Expanding/collapsing nodes
• Creating child pages or groups
• Quick navigation to page editor
• Visual hierarchy display

Collection Requirements

Your collection should have at minimum:

• A title field (or name, label, or hero.heading)
• A slug field (will be auto-generated if missing)
• A layout field for non-group pages (optional, will be initialized as empty array)

Example collection:

const Pages: CollectionConfig = {
  slug: 'pages',
  fields: [
    {
      name: 'title',
      type: 'text',
      required: true,
    },
    {
      name: 'slug',
      type: 'text',
      required: true,
      unique: true,
    },
    {
      name: 'layout',
      type: 'blocks',
      blocks: [
        // your blocks here
      ],
    },
    // The plugin will add: fullPath, parent, isGroup, isIndex, sort
  ],
}

Development

This plugin uses the standard Payload plugin structure.

Setup

1. Clone the repository
2. Install dependencies:

   pnpm install

3. Copy .env.example to .env and configure your database
4. Run the dev server:

   pnpm dev

Testing

Run the test suite:

pnpm test

Run integration tests:

pnpm test:int

Run E2E tests:

pnpm test:e2e

Building

Build the plugin for distribution:

pnpm build

This will:

1. Copy static assets
2. Generate TypeScript declarations
3. Compile source files with SWC

Publishing

The plugin is configured with semantic versioning and can be published to npm:

pnpm publish

Make sure to:

1. Update the version in package.json
2. Build the plugin before publishing
3. Test the built version

License

MIT

Support

For issues and feature requests, please use the GitHub issue tracker.