feat: expose pageTreeMoveContextKey to skip deploy hooks on tree moves

Author: CarloBu

README.md

@@ -117,6 +117,64 @@ nestedDocsPageTreePlugin({
 
 `labels` and `colors` are optional partial overrides. Missing entries fall back to the built-in defaults.
 
+## Drag-And-Drop Is Triggering A Deploy?
+
+A drag-and-drop move calls `payload.update()` on the draft only. The published version of the live site is never touched. So in most setups, dragging a page does not trigger any rebuild and you can skip this section.
+
+### When you can skip this section
+
+- The default Payload website template on Vercel (or any host using Next.js ISR), with drafts and autosave on. The template's `afterChange` hook only calls `revalidatePath` and `revalidateTag` from `next/cache`. Those just clear the edge cache. They do not trigger a Vercel build, do not consume build minutes, and do not change what visitors see when the published HTML hasn't changed.
+- Any setup where your `afterChange` hooks only do in-process cache work (`revalidatePath`, `revalidateTag`, in-memory caches, etc.).
+
+### When you need the one-line fix
+
+You need the fix if **you** wrote an `afterChange` hook that calls something external or expensive on every save. Common cases:
+
+- **Cloudflare Pages / Netlify / Vercel Deploy Hooks** (`fetch(DEPLOY_HOOK_URL)`) — these trigger full rebuilds and burn build minutes.
+- **GitHub Actions** `repository_dispatch` triggers.
+- **Manually-invoked SSG rebuilds**.
+- **Publish notifications** (email, Slack) on status transitions.
+- **Heavy search reindex jobs** (Algolia, Meilisearch full-document push).
+
+Why a tree move trips these: a typical deploy hook fires when `previousDoc?._status === 'published'` so that it catches unpublish events too. A tree move on a published doc matches that condition (the previous draft state was published) — but the live site hasn't actually changed. Without the fix, every drag fires your deploy.
+
+### The fix
+
+Add one line at the top of your hook. The plugin sets a flag on Payload's [hook context](https://payloadcms.com/docs/hooks/context) for every move, and your hook reads it to bail out early:
+
+```ts
+import { pageTreeMoveContextKey } from 'payload-nested-docs-page-tree'
+
+// at the top of your afterChange hook:
+if (req.context?.[pageTreeMoveContextKey]) return
+```
+
+This goes in **your** hook — the one that calls the deploy webhook. Not in any of the template's stock files.
+
+Full example:
+
+```ts
+import type { CollectionAfterChangeHook } from 'payload'
+import { pageTreeMoveContextKey } from 'payload-nested-docs-page-tree'
+
+export const triggerDeployOnPublishedChange: CollectionAfterChangeHook = async ({
+  doc,
+  previousDoc,
+  req,
+}) => {
+  // -- plugin opt-out --
+  if (req.context?.[pageTreeMoveContextKey]) return
+
+  // -- your deploy logic (example) --
+  // Fire on publish, republish, or unpublish — every transition the live site cares about.
+  if (doc._status === 'published' || previousDoc?._status === 'published') {
+    // POST to your Cloudflare / Netlify / Vercel deploy hook here
+  }
+}
+```
+
+See `dev/lib/rebuild.ts` for the full reference example.
+
 ## Configuration
 
 - `collections`: target collection slugs

dev/.env.example

@@ -1,2 +1,3 @@
 DATABASE_URL=mongodb://127.0.0.1/payload-plugin-template
 PAYLOAD_SECRET=YOUR_SECRET_HERE
+CLOUDFLARE_DEPLOY_HOOK_URL=

dev/app/(payload)/admin/importMap.js

@@ -2,6 +2,7 @@ import { SlugField as SlugField_2b8867833a34864a02ddf429b0728a40 } from '@payloa
 import { NestedDocsPageTreeListView as NestedDocsPageTreeListView_5b6451e48750080604c1786eb7b97ca9 } from 'payload-nested-docs-page-tree/rsc'
 import { CollectionCards as CollectionCards_f9c02e79a4aed9a3924487c0cd4cafb1 } from '@payloadcms/next/rsc'
 
+/** @type import('payload').ImportMap */
 export const importMap = {
   "@payloadcms/next/client#SlugField": SlugField_2b8867833a34864a02ddf429b0728a40,
   "payload-nested-docs-page-tree/rsc#NestedDocsPageTreeListView": NestedDocsPageTreeListView_5b6451e48750080604c1786eb7b97ca9,

dev/lib/rebuild.ts

@@ -0,0 +1,52 @@
+import type {
+  CollectionAfterChangeHook,
+  CollectionAfterDeleteHook,
+  PayloadRequest,
+} from 'payload'
+
+import { pageTreeMoveContextKey } from 'payload-nested-docs-page-tree'
+
+const postDeployHook = async (source: string, req: PayloadRequest): Promise<void> => {
+  const url = process.env.CLOUDFLARE_DEPLOY_HOOK_URL
+
+  if (!url) {
+    return
+  }
+
+  try {
+    await fetch(url, {
+      body: JSON.stringify({ source }),
+      headers: { 'content-type': 'application/json' },
+      method: 'POST',
+    })
+  } catch (error) {
+    req.payload.logger.error(error)
+  }
+}
+
+/**
+ * Trigger a deploy when a doc crosses the published boundary:
+ *   draft     → published   (publish / republish)
+ *   published → draft       (unpublish)
+ *
+ * Skips tree-only parent moves and autosave noise.
+ */
+export const revalidatePublishedChange =
+  (source: string): CollectionAfterChangeHook =>
+  async ({ doc, previousDoc, req }) => {
+    if (req.context?.[pageTreeMoveContextKey]) return
+    if (req.url?.includes('autosave=true')) return
+
+    if (doc._status === 'published' || previousDoc?._status === 'published') {
+      await postDeployHook(source, req)
+    }
+  }
+
+/** Trigger a deploy when a published doc is deleted. */
+export const revalidateOnDelete =
+  (source: string): CollectionAfterDeleteHook =>
+  async ({ doc, req }) => {
+    if (doc?._status !== 'published') return
+
+    await postDeployHook(source, req)
+  }

dev/payload.config.ts

@@ -9,6 +9,7 @@ import sharp from 'sharp'
 import { fileURLToPath } from 'url'
 
 import { testEmailAdapter } from './helpers/testEmailAdapter.js'
+import { revalidateOnDelete, revalidatePublishedChange } from './lib/rebuild.js'
 import { seed } from './seed.js'
 
 const filename = fileURLToPath(import.meta.url)
@@ -67,6 +68,10 @@ const buildPageLikeCollection = (args: {
     },
     slugField(),
   ],
+  hooks: {
+    afterChange: [revalidatePublishedChange(args.slug)],
+    afterDelete: [revalidateOnDelete(args.slug)],
+  },
   versions: {
     drafts: {
       autosave: {

package.json

@@ -1,6 +1,6 @@
 {
   "name": "payload-nested-docs-page-tree",
-  "version": "1.2.2",
+  "version": "1.2.3",
   "description": "Page tree plugin for Payload nested docs collections",
   "license": "MIT",
   "author": "WLF Studios",

src/components/PageTreeListView.client.tsx

@@ -27,9 +27,11 @@ import {
 import { useRouter, useSearchParams } from 'next/navigation'
 import React from 'react'
 
-import type {
-  NestedDocsPageTreePluginResolvedBadgeConfig,
-  PageTreeSourceDoc,
+import {
+  pageTreeMoveRequestHeader,
+  pageTreeMoveRequestHeaderValue,
+  type NestedDocsPageTreePluginResolvedBadgeConfig,
+  type PageTreeSourceDoc,
 } from '../types.js'
 
 import {
@@ -942,6 +944,7 @@ export default function PageTreeListViewClient({
           headers: {
             'Accept-Language': i18n.language,
             'Content-Type': 'application/json',
+            [pageTreeMoveRequestHeader]: pageTreeMoveRequestHeaderValue,
           },
           method: 'POST',
         },
@@ -996,6 +999,7 @@ export default function PageTreeListViewClient({
           headers: {
             'Accept-Language': i18n.language,
             'Content-Type': 'application/json',
+            [pageTreeMoveRequestHeader]: pageTreeMoveRequestHeaderValue,
           },
           method: 'POST',
         },

src/endpoints/createMovePageEndpoint.ts

@@ -7,7 +7,7 @@ import {
   getDocParentID,
   stringifyDocID,
 } from '../utilities/pageTree.js'
-import type { PageTreeSourceDoc } from '../types.js'
+import { pageTreeMoveContextKey, type PageTreeSourceDoc } from '../types.js'
 
 type MoveDocumentRequestBody = {
   parentID: null | string
@@ -326,6 +326,9 @@ export function createMovePageEndpoint(args: {
 
       await req.payload.update({
         collection: collectionSlug as never,
+        context: {
+          [pageTreeMoveContextKey]: true,
+        },
         data: {
           [parentFieldSlug]:
             body.parentID === null

src/index.spec.ts

@@ -1,8 +1,13 @@
-import type { CollectionConfig, Config } from 'payload'
+import type { CollectionBeforeChangeHook, CollectionConfig, Config } from 'payload'
 
 import { describe, expect, it } from 'vitest'
 
 import { nestedDocsPageTreePlugin } from './index.js'
+import {
+  pageTreeMoveContextKey,
+  pageTreeMoveRequestHeader,
+  pageTreeMoveRequestHeaderValue,
+} from './types.js'
 
 type CollectionEndpoint = NonNullable<Exclude<CollectionConfig['endpoints'], false>>[number]
 
@@ -14,6 +19,7 @@ function buildCollection(args: {
   endpointPath?: string
   includeBreadcrumbs?: boolean
   includeParent?: boolean
+  orderable?: boolean
   paginationDefaultLimit?: number
   parentFieldSlug?: string
   slug: string
@@ -25,6 +31,7 @@ function buildCollection(args: {
     endpointPath,
     includeBreadcrumbs = true,
     includeParent = true,
+    orderable = false,
     paginationDefaultLimit,
     parentFieldSlug = 'parent',
     slug,
@@ -87,6 +94,7 @@ function buildCollection(args: {
         ]
       : undefined,
     fields,
+    ...(orderable ? { orderable: true } : {}),
     slug,
   }
 }
@@ -235,6 +243,95 @@ describe('nestedDocsPageTreePlugin', () => {
     expect(config.collections?.[0]?.admin?.pagination?.defaultLimit).toBe(25)
   })
 
+  it('tags page-tree reorder requests with the move context before user hooks run', async () => {
+    let userHookSawMoveContext = false
+    const userBeforeChangeHook: CollectionBeforeChangeHook = ({ data, req }) => {
+      userHookSawMoveContext = req.context?.[pageTreeMoveContextKey] === true
+
+      return data
+    }
+    const config = nestedDocsPageTreePlugin({
+      collections: ['pages'],
+    })(
+      buildConfig([
+        {
+          ...buildCollection({
+            orderable: true,
+            slug: 'pages',
+          }),
+          hooks: {
+            beforeChange: [userBeforeChangeHook],
+          },
+        },
+      ]),
+    )
+    const hooks = config.collections?.[0]?.hooks?.beforeChange ?? []
+    const req = {
+      context: {},
+      headers: new Headers({
+        [pageTreeMoveRequestHeader]: pageTreeMoveRequestHeaderValue,
+      }),
+      user: { id: 'user-1' },
+    }
+    let data: Record<string, unknown> = {
+      title: 'About',
+    }
+
+    for (const hook of hooks) {
+      data = ((await hook({ data, req } as never)) ?? data) as Record<string, unknown>
+    }
+
+    expect(hooks).toHaveLength(2)
+    expect(req.context).toMatchObject({
+      [pageTreeMoveContextKey]: true,
+    })
+    expect(userHookSawMoveContext).toBe(true)
+  })
+
+  it('does not tag ordinary orderable updates as page-tree moves', async () => {
+    const config = nestedDocsPageTreePlugin({
+      collections: ['pages'],
+    })(buildConfig([buildCollection({ orderable: true, slug: 'pages' })]))
+    const hook = config.collections?.[0]?.hooks?.beforeChange?.[0]
+    const req = {
+      context: {},
+      headers: new Headers(),
+      user: { id: 'user-1' },
+    }
+
+    await hook?.({
+      data: {
+        title: 'About',
+      },
+      req,
+    } as never)
+
+    expect(req.context).not.toHaveProperty(pageTreeMoveContextKey)
+  })
+
+  it('does not tag the move context when the request has no authenticated user', async () => {
+    const config = nestedDocsPageTreePlugin({
+      collections: ['pages'],
+    })(buildConfig([buildCollection({ orderable: true, slug: 'pages' })]))
+    const hook = config.collections?.[0]?.hooks?.beforeChange?.[0]
+    const req = {
+      context: {},
+      headers: new Headers({
+        [pageTreeMoveRequestHeader]: pageTreeMoveRequestHeaderValue,
+      }),
+      user: null,
+    }
+
+    await hook?.({
+      data: {
+        title: 'About',
+      },
+      req,
+    } as never)
+
+    expect(req.context).not.toHaveProperty(pageTreeMoveContextKey)
+  })
+
   it('returns the original config when the plugin is disabled', () => {
     const config = buildConfig([
       buildCollection({