Payload Adsign Plugin

Revalidate Hook

Invalidate frontend cache when content changes

Deprecated. Prefer autoMode and opt collections/globals in via custom.revalidate. This page applies when mode: 'legacyMode' is set.

Usage

collections/Pages/index.ts
import { revalidateHook } from '@adsign/payload-adsign-plugin';

export const Pages: CollectionConfig = {
  hooks: {
    afterOperation: [
      revalidateHook({
        collection: 'pages',
        cacheTagFields: ['slug'],
      }),
    ],
  },
};

Options

OptionTypeDescription
collectionstringCollection slug (required)
cacheTagFieldsstring[]Fields to use as cache tags
collectionsstring[]Additional collections to revalidate
globalsstring[]Globals to revalidate
documentsDocument[]Specific documents to revalidate
revalidateRelationshipsboolean | objectIncoming fan-out — docs that reference this one (denylist)
revalidateRelatedstring[]Outgoing fan-out — own relationship/upload field names to follow

Examples

Revalidate with cache tag fields:

revalidateHook({
  collection: 'articles',
  cacheTagFields: ['slug'],
  collections: ['articles'],
})

Revalidate related documents (useful for media):

revalidateHook({
  collection: 'media',
  revalidateRelationships: true,
})

Scope the incoming fan-out (denylist — everything is included unless set to false):

revalidateHook({
  collection: 'media',
  revalidateRelationships: {
    collections: { products: false }, // fan out to all referencing collections except products
    globals: { menu: false },         // ...and all referencing globals except menu
  },
})

Follow the outgoing fan-out by naming own relationship fields:

revalidateHook({
  collection: 'campaigns',
  revalidateRelated: ['author'], // follow `author`, but not the costly `products` list
})

In autoMode, outgoing fan-out works the same way through custom.revalidate: fields a join declares are followed automatically, and revalidateRelated: ['fieldName'] is the allowlist for anything else.

Setup

  1. Configure in Payload:
payload.config.ts
adsignPlugin({
  siteName: 'My Site',
  domain: 'example.com',
  revalidation: {
    url: process.env.REVALIDATE_URL,
    secret: process.env.REVALIDATE_SECRET,
    batch: true,
  },
})
  1. Create API route in your frontend Next.js app:
app/api/revalidate/route.ts
import { revalidateTag } from 'next/cache';
import { NextRequest, NextResponse } from 'next/server';

export async function POST(request: NextRequest): Promise<Response> {
  const { secret, tag, tags } = await request.json();

  if (secret !== process.env.REVALIDATE_SECRET) {
    return NextResponse.json({ message: 'Invalid secret' }, { status: 401 });
  }

  const resolved = Array.isArray(tags) ? tags : typeof tag === 'string' ? [tag] : [];
  if (resolved.length === 0 || !resolved.every((t) => typeof t === 'string' && t.length > 0)) {
    return NextResponse.json({ message: 'Missing or invalid tag(s)' }, { status: 400 });
  }

  for (const t of resolved) {
    revalidateTag(t, { expire: 0 });
  }

  return NextResponse.json({ revalidated: true, now: Date.now() });
}

If the frontend already depends on @adsign/payload-adsign-plugin, use revalidateFromPayload from @adsign/payload-adsign-plugin/next instead — it handles both shapes for you. Don't add the plugin as a dependency just for this route; it peer-depends on payload@^3.0.0.

On this page

UsageOptionsExamplesSetup