@10xmedia/payload-audit

A Payload CMS plugin that provides two complementary audit features:

• Audit fields — automatically tracks createdBy and lastModifiedBy relationship fields on any collection or global
• Audit logs — full change history with before/after diffs, stored in a queryable audit-logs collection

Installation

pnpm add @10xmedia/payload-audit

// payload.config.ts
import { payloadAuditPlugin } from '@10xmedia/payload-audit'

export default buildConfig({
  plugins: [
    payloadAuditPlugin({ ... }),
  ],
})

Quick start

payloadAuditPlugin({
  collections: {
    posts: true,   // audit fields + full CRUD log
    users: {
      auditLog: true,  // log only, no createdBy/lastModifiedBy fields
    },
  },
  globals: {
    settings: true,
  },
})

Passing true enables both audit fields and audit logs with sensible defaults. Use an object to enable only what you need.

Documentation

• Audit fields — createdBy / lastModifiedBy field tracking
• Audit logs — CRUD change history, diffs, snapshots, auth events
• Custom events — business-specific audit entries via createAuditEvent
• Anonymization — handling PII and sensitive field values
• Multi-tenancy — per-tenant audit logs with @payloadcms/plugin-multi-tenant
• Data retention — automatic archiving to CSV and scheduled deletion via Jobs Queue
• Translations — built-in en/de/uk UI translations, adding custom languages
• TypeScript — type-safe access to diff and snapshot fields

TypeScript

Plugin configuration types:

import type {
  AuditPluginConfig,
  AuditOptions,
  GlobalAuditOptions,
  CollectionAuditLogConfig,
  GlobalAuditLogConfig,
  AnonymizeFunction,
  AuditFieldOptions,
  DataRetentionConfig,
  MultiTenancyConfig,
  OverrideFunction,
  ViewAccess,
} from '@10xmedia/payload-audit'

Type-safe diff and snapshot access — Payload generates these as a wide JSON union. Use the provided utilities to restore precise types:

import { typedDiff, typedSnapshot } from '@10xmedia/payload-audit'

const d = typedDiff<Post>(log.diff)
d.get('title')              // DiffEntry<string> | undefined
d.get('steps.abc123.title') // DiffEntry<string> | undefined
d.has('status')             // boolean

const post = typedSnapshot<Post>(log.snapshot)
post?.title                 // string | undefined

See TypeScript for the full API including DiffPaths<T>, DiffPathValue<T, P>, and typed changedPaths.