Overview

Summary generated from the README

Adds soft deletion to selected Payload collections by marking documents with a deletedAt field instead of removing them. Configured per collection in the plugins array, with options to enable restore, enable hard delete and restrict soft delete access. The plugin is in maintenance mode, as Payload 3.49.0 and later includes a built-in trash feature; it requires Payload 3.39.0 or later.

Features

Marks documents as deleted through a deletedAt field instead of removing them
Restore deleted documents from the admin panel
Modal confirmation for permanent hard delete
Per-collection toggles for restore and hard delete
Custom access function controlling who can soft delete
Query active or deleted documents via Local, REST and GraphQL APIs

Use cases

Prevent accidental permanent loss of content by editors
Let admins recover deleted posts or pages from the admin panel
Restrict permanent deletion to privileged roles on selected collections

Installation

npm i @payload-bites/soft-delete

Health Score

60/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/908347705-soft-delete.svg)](https://payloaddirectory.dev/plugins/908347705-soft-delete)

HTML

<a href="https://payloaddirectory.dev/plugins/908347705-soft-delete"><img src="https://payloaddirectory.dev/badge/908347705-soft-delete.svg" alt="Payload Directory"></a>

README

Soft delete

Never lose your Payload documents again, soft delete is here to save the day.

[!IMPORTANT] This plugin has been moved to maintenance mode due the release of the trash feature. From v3.49.0 onwards, I recommend using the implementation in the core product instead.

https://github.com/user-attachments/assets/4d7334d1-d7f2-4ab7-9421-0c84dfcf38cb

Compatibility table

Payload version	Soft delete version
v3.23.0 or earlier	Incompatible
v3.24.0 to 3.38.0	v1.x
v3.39.0 to 3.50.0	v2.x
v3.51.0 or later	v3.x

Quick start

Install the plugin:

pnpm add @payload-bites/soft-delete

Add the plugin to your payload.config.ts:

// ...
import { softDeletePlugin } from "@payload-bites/soft-delete";

export default buildConfig({
  // ...
  plugins: [
    // ...
    softDeletePlugin({
      collections: {
        posts: {},
        "posts-with-drafts": {
          // ...
          enableRestore: false,
          enableHardDelete: false,
          softDeleteAccess: (args) => args.req.user.role === "admin",
        },
      },
    }),
  ],
});

Defaults

For defaults, refer to defaults.ts.

Options

For options, refer to types.ts.

Querying

You can retrieve active or soft deleted documents by checking for the existence of the deletedAt field.

Local API

const result = await payload.find({
  collection: "posts",
  where: {
    deletedAt: {
      exists: false,
    },
  },
});

REST API

import { stringify } from "qs-esm";
import type { Where } from "payload";

const query: Where = {
  deletedAt: {
    exists: false,
  },
};

const getPosts = async () => {
  const stringifiedQuery = stringify(
    {
      where: query,
    },
    { addQueryPrefix: true },
  );

  const response = await fetch(
    `http://localhost:3000/api/posts${stringifiedQuery}`,
  );
};

GraphQL API

query {
  Posts(where: { deletedAt: { exists: false } }) {
    docs {
      title
    }
  }
}

Caveats

It is currently not possible to soft delete a draft document that has invalid fields (e.g. required) unless the document has a previously valid published version or you resolve the invalid fields.

Roadmap

Add modal to hard delete.
Enable/disable restore functionality per collection.
Enable/disable hard delete functionality per collection.
Schedule automatic deletion after certain number of days.
Documentation (including API examples).
Translations.

soft delete