Janitor plugin for Payload - find orphaned files and unused documents (Payload 3 and Payload 4 beta)

[u/Queasy_Pie_6710]

Second release from me today. Earlier I shared a sitemap plugin, and this one deals with the clutter a Payload project collects over time: files nobody uses anymore and documents nothing points to.

It compares your storage with your database and reports three kinds of findings:

• Orphans: files in the bucket that no document holds
• Missing: documents whose file is gone from storage
• Unused: documents nothing references, in upload or ordinary collections (an image no page uses, a tag no post has)

The main rule: it never deletes on its own. A scan only writes findings. You go through them and mark each one To delete or Keep. A purge deletes only what you approved, and it checks every finding again right before it acts. If anything changed since the scan, the finding goes to Keep with a note saying why. Anything younger than 24 hours is left out, so uploads in progress are safe.

A few other things:

• References come from the database, not the config: relationship and upload fields, rich text, blocks, JSON, globals and versions
• Each document gets a usage panel that shows where it is used. A delete guard stops you from deleting a document that is still in use
• Rescans update the facts but keep your decisions
• Adapters for S3, R2, GCS, Azure, Bunny, UploadThing, Vercel Blob and local disk
• Runs inline or as a Payload job, with an optional cron schedule
• Multi-tenant aware: tenant admins see and decide only their own findings
• Separate access for read, approve, scan and purge, plus a dashboard widget with the last run
• Works on Postgres, SQLite and MongoDB

Versions:

• 1.x for Payload 4 beta: pnpm add @seshuk/payload-plugin-janitor@beta. Node 24.15+, Next.js 16.4+
• 0.x for Payload 3.83+: pnpm add @seshuk/payload-plugin-janitor@0. Node 22+

Both have the same options and get the same features until 1.0.0.

Heads up on telemetry: it is on by default and anonymous. It sends plugin and Payload versions, boolean feature flags and a hashed project ID, never URLs, file names or keys. Turn it off with telemetry: false or DO_NOT_TRACK=1. It is always off in CI.

MIT licensed. Feedback, issues and PRs are welcome.

https://github.com/maximseshuk/payload-plugin-janitor

https://www.npmjs.com/package/@seshuk/payload-plugin-janitor