Strapi Plugin Paper Trail for Strapi V5 (Enhanced)

Accountability and content versioning for Strapi v5+ with enhanced UI, field-level restoration and auto-refresh.

This is a fork of the original strapi-plugin-paper-trail with the following enhancements:

• Improved UI with larger font sizes throughout
• Field-level restoration - select which fields to restore from previous versions
• Auto-refresh functionality - automatically updates after content changes
• Better auth handling - fixes authentication issues during restoration
• Vanilla JavaScript fallback - works even when React components fail to load

Requirements

1. node v18 or higher
2. strapi v5.0 or higher

Features

• Automatic revision history and auditing with support for all major strapi content types including relations, media, components, and dynamic zones via the admin panel.
• Support for collection and single content types.
• Roll-back capabilities with the option to select specific fields to restore via the admin panel.
• Tracks revision history by both admins and users.
• Internationalization (i18n) plugin support.

Installation

To install this plugin, you need to add an NPM dependency to your Strapi application:

# Using Yarn
yarn add strapi-plugin-paper-trail-v5

# Or using NPM
npm install strapi-plugin-paper-trail-v5 --save

Enable the plugin by adding the following in ./config/plugins.js.

module.exports = {
  // ...
  'paper-trail': {
    enabled: true,
    resolve: './node_modules/strapi-plugin-paper-trail-v5'
  }
  // ...
};

Or, if you are using TypeScript, in ./config/plugins.ts.

export default {
  // ...
  'paper-trail': {
    enabled: true,
    resolve: './node_modules/strapi-plugin-paper-trail-v5'
  }
  // ...
};

Heads up! Disabling the plugin will destroy the Paper Trail model and everything in it, clearing your revision history.

Then, you'll need to build your admin panel:

# Using Yarn
yarn build

# Or using NPM
npm run build

Usage

The functionality of this plugin is opt-in on a per content type basis and can be disabled at any time.

Important Change for Strapi V5

In Strapi V5, the Paper Trail toggle in the Content-Type Builder UI is read-only. You must configure Paper Trail by directly editing the content type's schema.json file.

To enable Paper Trail for a content type, modify the pluginOptions object in your model's schema.json:

  // ...
  "pluginOptions": {
    "paperTrail": {
      "enabled": true
    }
  },
  // ...

Once enabled on the model, Paper Trail will be listening for changes to your records and will automatically create revisions when records are created or updated. These changes can be viewed directly from the content manager edit view.

For convenience, the plugin will differentiate CREATE from UPDATE and will display which user made the change (regardless of whether they are an admin or a user permissions plugin user).

Clicking 'View all' will show the entire revision history for this record.

The revision history for each field that was touched during the CREATE or UPDATE will be displayed, and you are able to select which fields you would like to restore by checking the checkbox on each accordion.

Once you are ready, you will get a final chance to review the entire scope of the fields that will be restored. You can also view the JSON object for debugging purposes (or simply as a way to quickly grok the entire change).

Clicking 'Restore' will then immediately overwrite the selected fields on the original record, restoring your revision.

Debugging

If you encounter issues with the Paper Trail panel not appearing in the content manager, you can use the browser console to debug:

// Check if the plugin is registered and properly initialized
window.debugPaperTrailPlugin();

// Force inject the Paper Trail component if it's not visible
window.paperTrailForceInject();

// Force refresh the Paper Trail panel to get latest version information
window.paperTrailForceRefresh();

// Use vanilla JavaScript implementation (for when React components fail)
window.injectVanillaPaperTrail();

Troubleshooting

If the Paper Trail panel doesn't appear in the content manager:

1. Make sure Paper Trail is enabled for the content type in its schema.json
2. Rebuild the admin panel with npm run build
3. Restart Strapi with npm run develop
4. Check the browser console for any error messages
5. Open your browser console and run window.debugPaperTrailPlugin()
6. If needed, try forcing the component injection with window.paperTrailForceInject()

Notes & Considerations

While we have tried to keep the plugin as simple and intuitive to use as possible, there are some notes and considerations to mention. Some of these are strapi specific, some are specific to the challenge of version control, and others are plugin specific challenges.

1. The plugin has been updated to work with Strapi V5.

2. The plugin relies on the content type plugin UID property to identify the correct content type and associate the revision history. If you change this value you will lose previous revision histories (all revision history records can be manually browsed and modified from Content Manager > Collection Types > Trail).

3. This has not been tested with all available custom field plugins, however as long as the custom field plugin implements on top of the core strapi content manager types (e.g. string, text, biginteger, json, component, and so on) and isn't doing anything too arcane, then it should be fine.

4. The plugin is a middleware listening on the admin and user content management endpoints. Making changes directly to the records outside of this scope (e.g. from a custom service or controller) will not be logged as a revision by the plugin, however it shouldn't be difficult to manually implement this if needed.

5. Attempting to restore a unique field with a duplicate value will cause the request to fail.

6. Likewise, attempting to restore a field that has been since deleted from the schema or renamed will cause the attempt to fail (restoration of a delete field is on the roadmap)

7. password type is not supported for security reasons.

8. The plugin is still in early development, use with caution!

9. Pull requests for new features and fixes welcome and encouraged 🚀

Roadmap

In no particular order and subject to change depending on priorities.

1. Compare diffs against current vs chosen revision, or two separate revisions.
2. Restoration for records deleted by DELETE event.
3. Small enhancements to better leverage available strapi server hooks instead of custom code.
4. Better support for only logging changed fields (currently the strapi admin sends the entire record back and not just the changes fields) to reduce revision noise.
5. Plugin management panel for purging revision history.
6. Selecting which field to send the revised change to on the record (supporting schema name changes).

Support

Please create an issue in the issue tracker if you have a problem or need support. Please select the correct label when creating your issue (e.g. help wanted or bug).

Contributing

Contributions are welcome. Note that code style is enforced with prettier. Kindly adhere to this while making contributions.

Step 1: Fork this repo

Step 2: Start hacking

Step 3: Open a PR

Step 4: Profit 💰💰💰

License

MIT License