Payload CMS: Document Locking Issue With Autosave

by Admin 50 views
Payload CMS Document Locking Bug with Autosave Enabled

Hey guys! Let's dive into a quirky issue in Payload CMS that some of you might have encountered: document locking not working properly when autosave is turned on. This can lead to some real headaches, especially when multiple users are collaborating on the same content. Let's break down the problem, how to reproduce it, and what areas are affected.

The Core Issue: Document Locking vs. Autosave

So, what's the deal? In Payload CMS, the document locking feature is designed to prevent multiple users from editing the same document simultaneously. This is super important to avoid conflicts and ensure that no one's work gets overwritten. Ideally, when one user opens a document for editing, a lock should appear, notifying other users that the document is currently being worked on.

Now, here’s where autosave comes into the picture. Autosave, as the name suggests, automatically saves the document at regular intervals (by default, every 100ms in Payload CMS). This is awesome for preventing data loss, but it creates a conflict with the document locking mechanism.

Here's the problem in a nutshell: When autosave is enabled, every time a user types or makes a change, the document gets saved almost instantly. This means there are virtually no “unsaved changes” for the locking system to detect. As a result, multiple users can jump in and edit the same document without any warnings or locks appearing. This can lead to some serious chaos, where changes made by one user are overwritten by another, leaving everyone frustrated. Imagine spending an hour crafting the perfect paragraph, only to have it vanish into the digital ether!

To make it crystal clear, here’s the scenario:

  1. User A and User B both open the same post in Payload CMS for editing.
  2. User A makes some changes, and boom, the post gets autosaved.
  3. User B, unaware of User A's edits, makes their own changes, and the post gets autosaved again.
  4. User A’s hard work is overwritten by User B’s changes, and that's not cool.
  5. The real kicker? No lock icon is displayed to either user during this whole process, so they are completely in the dark about the potential conflict.

This is a classic case of two features working against each other, and it highlights the importance of carefully considering how different functionalities interact within a system.

Reproducing the Bug: A Step-by-Step Guide

Okay, so you're probably thinking, "How can I see this in action myself?" No worries, I've got you covered. Here’s a step-by-step guide to reproduce this bug in Payload CMS. This will help you understand the issue firsthand and potentially contribute to finding a solution.

  1. Create a new Payload app: Kick things off by creating a brand-new Payload CMS application using the command npx create-payload-app. This will give you a clean slate to work with and ensure that no existing configurations are interfering with the test.
  2. Run the app in production environment: It’s crucial to run the app in a production environment to accurately simulate real-world conditions. This is because certain behaviors and optimizations might differ between development and production modes.
  3. Create the first user: Navigate to localhost:3000/admin (or your specific admin URL) and create the initial user account. This user will have administrative privileges and will be used to set up the system.
  4. Seed the database: Seeding the database means populating it with some initial data, like posts or articles. This will give you some content to play around with and edit, making it easier to observe the locking issue. You can use a script or manually add some entries.
  5. Log in simultaneously with two users: This is the heart of the reproduction process. Open two separate browser windows (or use different browsers) and log in with the user you just created and another user (e.g., one that you seeded). This simulates two different users working on the same site.
  6. Go to the Posts collection: In both browser windows, navigate to the Posts collection (or whichever collection you want to test). This is where you’ll see the documents that can be edited.
  7. Try editing a document simultaneously: Here’s where the magic happens (or rather, the bug!). In both windows, open the same document for editing. Start making changes in one window, and then switch to the other window and make different changes. Notice anything?
  8. Observe the lack of lock: You should observe that there is no lock icon displayed on the document in either window, even though both users are actively editing it. This is the core of the problem. The document locking mechanism is not functioning as expected due to the autosave feature.
  9. Witness the overwritten changes: After making changes in both windows, save the document (or let autosave do its thing). You’ll likely find that the changes made by the last user to save have overwritten the changes made by the first user. This is the data loss that we’re trying to prevent with document locking!

By following these steps, you can reliably reproduce the document locking bug and see firsthand how it affects the editing experience. This is super helpful for understanding the issue and communicating it effectively to the Payload CMS team or other developers.

Code to Reproduce

For those of you who like to dig into the code, there's a handy reproduction available at https://github.com/shaheer-alam2/doc-saving-issue. This repository provides a minimal setup that demonstrates the issue, making it easier to investigate and potentially propose fixes.

Areas Affected: Core Functionality

This bug squarely affects the core functionality of Payload CMS. Document locking is a fundamental feature for collaborative content management, and when it doesn't work correctly, it can lead to significant data loss and frustration for users. This is especially critical for teams working on complex projects where multiple people need to contribute to the same content.

Environment Details

To give you a complete picture, here are the details of the environment where this bug was observed:

Binaries:
  Node: 22.16.0
  npm: 10.9.2
  Yarn: N/A
  pnpm: 10.18.1
Relevant Packages:
  payload: 3.62.1
  next: 15.4.4
  @payloadcms/db-postgres: 3.62.1
  @payloadcms/drizzle: 3.62.1
  @payloadcms/email-nodemailer: 3.62.1
  @payloadcms/graphql: 3.62.1
  @payloadcms/live-preview: 3.62.1
  @payloadcms/live-preview-react: 3.62.1
  @payloadcms/next/utilities: 3.62.1
  @payloadcms/payload-cloud: 3.62.1
  @payloadcms/plugin-form-builder: 3.62.1
  @payloadcms/plugin-nested-docs: 3.62.1
  @payloadcms/plugin-redirects: 3.62.1
  @payloadcms/plugin-search: 3.62.1
  @payloadcms/plugin-seo: 3.62.1
  @payloadcms/richtext-lexical: 3.62.1
  @payloadcms/translations: 3.62.1
  @payloadcms/ui/shared: 3.62.1
  react: 19.1.0
  react-dom: 19.1.0
Operating System:
  Platform: linux
  Arch: x64
  Version: #1 SMP PREEMPT_DYNAMIC Thu Jun  5 18:30:46 UTC 2025
  Available memory (MB): 7805
  Available CPU cores: 8

This information is super valuable for developers trying to diagnose the issue, as it helps pinpoint potential compatibility problems or environment-specific factors.

Wrapping Up

The document locking issue in Payload CMS when autosave is enabled is a significant problem that can impact collaborative workflows. By understanding the bug, how to reproduce it, and the affected areas, we can work together to find a solution. Whether you’re a developer, a content creator, or just a Payload CMS enthusiast, your insights and contributions are valuable. Let's keep the conversation going and make Payload CMS even better!

If you've experienced this issue, or have any thoughts on potential solutions, please share your comments below! Let's help each other out and ensure a smooth content editing experience for everyone.