Overview

Summary generated from the README

Connects Payload to a separate Vercel frontend project so editors can rebuild the site without a Vercel login. It tracks pending changes on opted-in collections and globals, runs debounced automatic deploys, and records each deployment in a ledger collection. With an optional Vercel token it also shows status and history and supports cancel and rollback. Requires Payload 3.88 or later.

Features

Deploy button and status pill in the admin header on every page
Pending-changes tracking per document with Not deployed yet or Live pills
Automatic deploys after a 60 second quiet period with a 10 minute maximum wait
Deployments ledger collection with who, why, what changed, state, URL and duration
Cancel and roll back deployments, with failed builds returning changes to pending
Local API methods and optional signed webhook receiver for status updates

Use cases

Rebuild a static Astro or Next export on Vercel whenever editors publish content
Show editors which saved changes are not yet live on the website
Roll back or cancel a bad deployment from the Payload admin without a Vercel account

Installation

npm i @payload-solutions/plugin-vercel

Health Score

66/100Good

Composite score based on GitHub activity, stars, npm downloads, publish recency, dependency count, and package size.

Badge for your README

Markdown

[![Payload Directory](https://payloaddirectory.dev/badge/1356812914-plugin-vercel.svg)](https://payloaddirectory.dev/plugins/1356812914-plugin-vercel)

HTML

<a href="https://payloaddirectory.dev/plugins/1356812914-plugin-vercel"><img src="https://payloaddirectory.dev/badge/1356812914-plugin-vercel.svg" alt="Payload Directory"></a>

README

@payload-solutions/plugin-vercel

Vercel Integration for Payload CMS. Your frontend is a separate Vercel project — Astro, a static Next export, a second Next app — and it has to be rebuilt when editors publish. This plugin gives editors a Deploy button on every admin page, shows what is waiting to go live, deploys automatically one minute after the last change, follows every deployment on Vercel, and can cancel or roll back from the same place. Nobody needs a Vercel login.

import { vercelPlugin } from '@payload-solutions/plugin-vercel'

vercelPlugin({
  targets: [{ slug: 'production', label: 'Website', hook: process.env.VERCEL_DEPLOY_HOOK_PRODUCTION, url: 'https://example.com' }],
  token: process.env.VERCEL_TOKEN, // optional: status, history, cancel, rollback
  collections: { pages: true, posts: true },
  globals: { header: true },
})

Docs: https://payload.solutions/docs/plugins/vercel-integration

Install

pnpm add @payload-solutions/plugin-vercel

Peer dependencies: payload ^3.88, @payloadcms/ui, @payloadcms/next, react, react-dom. No runtime dependencies.

What it does

Targets — one deploy hook per site or environment (production, staging, a docs site). The Vercel project id is read from the hook URL. A target whose env var is unset shows as not configured and never throws.
Pending changes — afterChange/afterDelete hooks on the collections and globals you opt in record one row per document per target (a document saved twenty times is one row). Collections with drafts count publishes and unpublishes only. The admin header shows "3 changes · deploying in 0:42"; every tracked document carries a Not deployed yet / Live pill.
Automatic deploys — changes open a debounce window (60 s quiet period, 10 min max wait). The window is fired by any tick: the header widget's own status poll, a sendBeacon when the tab closes, the vercel-tick scheduled task, or POST /api/vercel/tick from a cron — so it works on Vercel Hobby (whose cron runs once a day) with zero extra infrastructure.
Ledger — every trigger is a row in vercel-deployments with who, why, what changed (capped summary), and, with a token, the Vercel deployment id, state, URL, duration and error. Bounded by retention (90 days / 200 rows per target).
Failure semantics — a failed or canceled build puts its changes back into pending; a rollback re-instates everything newer than the restored deployment. A build that Vercel canceled because a newer hook call arrived is marked superseded, not failed.
Status — with VERCEL_TOKEN: polling (/v7/deployments, /v13/deployments/{id}) plus an optional signed webhook receiver (POST /api/vercel/webhook, HMAC-SHA1 x-vercel-signature, Pro/Enterprise accounts).
Admin — header widget (admin.components.actions), Deployments view (/admin/deployments), document pill (beforeDocumentControls), and the deployments collection list. Built from @payloadcms/ui components.
Local API — payload.vercel.deploy(), .status(), .pending(), .markChanged(), .pause(), .cancel(), .rollback(), .tick().

Screenshots

_{Deploy from any admin page, with a reason and the changes it carries.}	_{Every tracked document says whether it is live yet.}
_{A failed build keeps its changes pending.}	_{The header pill on every admin page.}

More in the documentation: https://payload.solutions/docs/plugins/vercel-integration

Development

pnpm dev:mock-vercel   # mock Vercel on :3399 (deploy hooks, deployments API, cancel, rollback)
pnpm dev               # admin on :3400, [email protected] / test — copy dev/.env.example to dev/.env first
pnpm test:unit         # pure logic
pnpm test:int          # real Payload + sqlite against the mock
pnpm test:e2e          # Playwright, starts both servers

Vercel is a trademark of Vercel, Inc. This plugin is not affiliated with or endorsed by Vercel.

plugin vercel