@focus-reactive/payload-plugin-schedule-publication

Scheduled publication plugin for Payload CMS v3. Set a future publish date on any draft document and it goes live automatically — no manual publishing required.

The plugin enables Payload's built-in schedulePublish drafts feature on selected collections and globals, routes the resulting jobs through an isolated queue, and exposes a Bearer-token-protected endpoint that your cron job pings to drain the queue.

AI Integration Prompt

Copy and paste this prompt into your AI assistant (Cursor, Claude, etc.) to integrate the plugin into an existing Payload project.

I want to add scheduled publication to my Payload CMS v3 project using @focus-reactive/payload-plugin-schedule-publication.

## How it works

The plugin:
1. Enables `drafts.schedulePublish: true` on every collection/global you configure — this makes Payload
   show a "Schedule Publish" date-time picker in the admin sidebar.
2. Routes all `schedulePublish` jobs to an isolated queue (default: "scheduled-publish") so they don't
   interfere with other background jobs.
3. Registers a GET /api/scheduled-publish/run endpoint that, when hit by a cron, calls
   payload.jobs.run({ queue }) to process all due scheduled-publish jobs.
4. The endpoint requires an Authorization: Bearer <secret> header to prevent unauthorized triggers.

## Installation

pnpm add @focus-reactive/payload-plugin-schedule-publication

## Step 1 — Register the plugin in payload.config.ts

import { schedulePublicationPlugin } from '@focus-reactive/payload-plugin-schedule-publication'

// Inside buildConfig({ plugins: [...] })
schedulePublicationPlugin({
  collections: ['pages', 'posts'],  // slugs of collections to enable scheduled publishing on
  globals: ['site-settings'],       // slugs of globals to enable scheduled publishing on (optional)
  secret: process.env.CRON_SECRET!, // any env var you choose — must match the Bearer token your cron sends
})

## Step 2 — Set up a cron to trigger the endpoint

The endpoint GET /api/scheduled-publish/run must be called at least as often as your finest
scheduling granularity (e.g. every minute for minute-level precision).

Pass the secret as a Bearer token:
  Authorization: Bearer <your-secret>

### Vercel (vercel.json)

{
  "crons": [
    {
      "path": "/api/scheduled-publish/run",
      "schedule": "* * * * *"
    }
  ]
}

Note: Set CRON_SECRET in your Vercel project environment variables. Vercel automatically sends
this value in the Authorization header when triggering your cron. Pass it directly to the
plugin's secret option: secret: process.env.CRON_SECRET!

### Any HTTP client / external cron service

curl -X GET https://your-cms.com/api/scheduled-publish/run \
  -H "Authorization: Bearer YOUR_SECRET"

## Important notes

- collections and globals receive `versions.drafts.schedulePublish: true` automatically.
  If a collection already has a versions/drafts config it is preserved and merged.
- The queue option (default: "scheduled-publish") isolates schedule jobs. Change it only if
  you have a naming conflict with other queues.
- Never expose the secret in client-side code. Store it in an environment variable.

How It Works

Editor sets "Schedule Publish" date in Payload Admin
              ↓
Payload creates a schedulePublish job in the jobs collection
              ↓
         [ queue: "scheduled-publish" ]
              ↓
Cron calls GET /api/scheduled-publish/run  (every minute)
              ↓
Plugin endpoint: payload.jobs.run({ queue: "scheduled-publish" })
              ↓
Due jobs are processed → documents are published

The plugin hooks into Payload's own schedulePublish task — it does not implement its own publish logic. It simply enables the feature on your chosen collections/globals, routes the jobs to a dedicated queue, and provides the HTTP trigger endpoint.

Installation

pnpm add @focus-reactive/payload-plugin-schedule-publication

Peer dependencies: payload ^3.0.0

Quick Start

Step 1 — Register the plugin

// payload.config.ts
import { buildConfig } from "payload";
import { schedulePublicationPlugin } from "@focus-reactive/payload-plugin-schedule-publication";

export default buildConfig({
  plugins: [
    schedulePublicationPlugin({
      collections: ["pages"],
      secret: process.env.CRON_SECRET!,
    }),
  ],
});

The plugin injects into every configured collection and global:

• versions.drafts.schedulePublish: true — enables the "Schedule Publish" date picker in the admin sidebar
• All schedulePublish jobs are routed to the "scheduled-publish" queue via a beforeChange hook on the jobs collection

Step 2 — Set up a cron

The endpoint GET /api/scheduled-publish/run must be called periodically (at least as often as your finest scheduling granularity). It processes all due jobs in the queue and returns { ok: true }.

Vercel

Add a cron to vercel.json at the root of your project:

{
  "crons": [
    {
      "path": "/api/scheduled-publish/run",
      "schedule": "* * * * *"
    }
  ]
}

Vercel automatically sends CRON_SECRET as Authorization: Bearer $CRON_SECRET when triggering crons. Set CRON_SECRET in your Vercel project settings and pass it directly to the plugin's secret option.

External cron / curl

curl -X GET https://your-cms.com/api/scheduled-publish/run \
  -H "Authorization: Bearer YOUR_SECRET"

Node.js (node-cron)

import cron from "node-cron";

cron.schedule("* * * * *", async () => {
  await fetch("http://localhost:3000/api/scheduled-publish/run", {
    headers: {
      Authorization: `Bearer ${process.env.CRON_SECRET}`,
    },
  });
});

Configuration Reference

interface SchedulePublicationPluginConfig {
  /**
   * Collection slugs to enable scheduled publishing for.
   * @example ['pages', 'posts']
   */
  collections?: string[];

  /**
   * Global slugs to enable scheduled publishing for.
   * @example ['site-settings']
   */
  globals?: string[];

  /**
   * Queue name to isolate schedulePublish jobs.
   * When set, jobs are routed to this queue and the /scheduled-publish/run
   * endpoint will only process this queue.
   * @default "scheduled-publish"
   */
  queue?: string;

  /**
   * Bearer token used to authenticate calls to the
   * GET /api/scheduled-publish/run endpoint.
   */
  secret: string;
}

Options

The Run Endpoint

GET /api/scheduled-publish/run

Triggers processing of all due jobs in the scheduled-publish queue.

Authentication: Authorization: Bearer <secret>

Success response:

{ "ok": true }

Error responses:

{ "error": "Unauthorized" }   // 401 — missing or wrong token
{ "error": "Internal server error" }  // 500 — jobs runner threw

Environment Variables

The plugin's secret option accepts any environment variable — use whatever name fits your platform. On Vercel, the natural choice is CRON_SECRET, which Vercel automatically sends as the Authorization: Bearer header when triggering crons.

// On Vercel
secret: process.env.CRON_SECRET!

// On any other platform
secret: process.env.MY_CRON_SECRET!

Versioning & Drafts Behaviour

The plugin calls injectSchedulePublishToVersions on each configured collection/global config:

• If the collection has no versions config → adds { drafts: { schedulePublish: true } }
• If versions is true or has drafts: true → replaces drafts with { schedulePublish: true }
• If versions.drafts is an object → merges schedulePublish: true into it, preserving other draft options (e.g. autosave)

Your existing versions/drafts configuration is never discarded.

Exports Reference