payload-plugin-admin-alerts

Dashboard system alerts for the Payload CMS admin UI. Author messages from the admin panel, target an audience (everyone or specific users), and let users dismiss them individually.

Features

• admin-alerts collection for authoring messages (title, content, type, audience, dismissable flag)
• Per-user dismissals tracked inline on the alert via a dismissedBy relationship field — no extra collection
• Alert types: info, success, warning, error
• Audience targeting: broadcast to all authenticated users, or pick specific users
• "Active" / "Inactive" status for taking alerts down without deleting them
• Dashboard panel that fetches and renders alerts on the admin home page
• Per-user dismissal endpoint (POST /admin-alerts/:id/dismiss)
• Access control: only the alert author can edit or delete; any authenticated user can read

Installation

pnpm add payload-plugin-admin-alerts
# or: npm install payload-plugin-admin-alerts
# or: yarn add payload-plugin-admin-alerts

Peer requirements: payload ^3.0.0, @payloadcms/ui ^3.0.0, react ^18 || ^19, react-dom ^18 || ^19.

Usage

Add the plugin to your payload.config.ts:

import { buildConfig } from 'payload'
import { payloadAdminAlerts } from 'payload-plugin-admin-alerts'

export default buildConfig({
  plugins: [
    payloadAdminAlerts({
      // defaults shown
      disabled: false,
      usersCollectionSlug: 'users',
    }),
  ],
  // ...
})

That's it. After Payload restarts you'll see a System → Admin Alerts entry in the admin nav and a new alerts panel on the dashboard.

Configuration

type PayloadAdminAlertsConfig = {
  /**
   * Disable the runtime behavior (dashboard UI + endpoints) while keeping
   * the collections registered, so the database schema stays consistent.
   * @default false
   */
  disabled?: boolean

  /**
   * Auth collection slug used for alert authors and audience targeting.
   * @default 'users'
   */
  usersCollectionSlug?: string
}

| Option | Type | Default | Notes | | --------------------- | --------- | --------- | ---------------------------------------------------------------------------------------------------- | | disabled | boolean | false | Skips registering the dashboard component and endpoints. Collections stay so migrations don't break. | | usersCollectionSlug | string | 'users' | Used by the createdBy and targetUsers relationship fields, and by access control checks. |

Creating alerts from hooks

Alerts are a normal Payload collection (admin-alerts). Create them from any collection hook, job, or endpoint with the Local API — for example, notify editors when content goes live:

import type { CollectionAfterChangeHook, CollectionConfig } from 'payload'

const alertOnPublish: CollectionAfterChangeHook = async ({
  doc,
  operation,
  previousDoc,
  req,
  context,
}) => {
  // Only run once per publish, not on every save
  if (context.skipAdminAlert) return
  if (operation !== 'update') return
  if (doc._status !== 'published' || previousDoc?._status === 'published') return

  await req.payload.create({
    collection: 'admin-alerts',
    data: {
      title: `Published: ${doc.title}`,
      content: 'A new post is live. Review it from the dashboard if needed.',
      type: 'success',
      status: 'active',
      audience: 'all',
      dismissable: true,
    },
    req, // pass req so the alert stays in the same transaction
    user: req.user, // createdBy is auto-set from the authenticated user
  })
}

export const Posts: CollectionConfig = {
  slug: 'posts',
  versions: { drafts: true },
  hooks: {
    afterChange: [alertOnPublish],
  },
  fields: [
    { name: 'title', type: 'text', required: true },
    // ...
  ],
}

Target a specific user (for example, the post author) instead of broadcasting:

await req.payload.create({
  collection: 'admin-alerts',
  data: {
    title: 'Your draft was rejected',
    content: 'An editor left feedback on your submission.',
    type: 'warning',
    status: 'active',
    audience: 'selected',
    targetUsers: [authorId],
    dismissable: true,
  },
  req,
  user: req.user,
})

Notes

• Pass req into nested create calls so the alert participates in the same database transaction as the triggering operation.
• Pass user: req.user when the hook runs in an authenticated request; the plugin sets createdBy automatically on create.
• For system/cron contexts with no req.user, use overrideAccess: true and set createdBy yourself if you need an author for update/delete access.
• Use req.context flags (for example context.skipAdminAlert) if your hook chain could re-trigger itself.

Collections

admin-alerts

Authored from the admin panel. Fields:

| Field | Type | Purpose | | -------------- | ------------------ | -------------------------------------------------------------------------------------- | | title | text, required | Heading shown on the dashboard card | | content | textarea, required | Body text | | type | select | info / success / warning / error — drives the styling | | status | select | active / inactive — only active alerts are surfaced | | dismissable | checkbox | If true, users can dismiss the alert for themselves | | audience | select | all or selected | | targetUsers | relationship[] | Shown only when audience === 'selected' | | createdBy | relationship | Auto-populated on create, read-only | | dismissedBy | relationship[] | Users who have dismissed this alert; edit to re-show or pre-dismiss for specific users | | alertPreview | ui field | Live preview of how the alert will render on the dashboard |

Dismissals

Dismissals live on the alert itself as the dismissedBy relationship array — no separate collection. POST /admin-alerts/:id/dismiss appends the requesting user to the field; the dashboard query filters out alerts where the current user appears in dismissedBy. To re-show an alert to a specific user, remove them from dismissedBy. To re-broadcast to everyone who'd dismissed it, clear the field.

Endpoints

The plugin registers two endpoints (mounted under your Payload API route, typically /api):

| Method | Path | Description | | ------ | --------------------------- | ----------------------------------------------------------- | | GET | /admin-alerts/dashboard | Returns { alerts: DashboardAlert[] } for the current user | | POST | /admin-alerts/:id/dismiss | Records a dismissal for the current user |

Both require an authenticated request.

Access control

• Read any alert: any authenticated user
• Create an alert: any authenticated user (you become createdBy)
• Update / Delete: only the user who authored the alert

Dismissals are write-only and scoped to the requesting user.

Local development

pnpm install
pnpm dev          # starts the dev/ Payload app on http://localhost:3000
pnpm test:unit    # vitest unit tests
pnpm test:e2e     # playwright e2e tests
pnpm check        # typecheck + lint + tests

The dev/ directory contains a minimal Payload app preconfigured with the plugin.

Publishing

pnpm publish

prepublishOnly cleans dist/ and rebuilds. publishConfig swaps the source-pointing exports for the compiled dist/ outputs at publish time, so consumers always get the built files.

License

MIT

Media

This plugin was tested and developed in relation to my upcoming fairytale builder app.