News from the Product Desk: Real-time collaboration in Documents

Starting version 17.0 – currently planned for January 2026, OpenProject introduces a completely redesigned Documents module with real-time collaboration capabilities. This marks a significant step forward in how teams can work together within OpenProject, enabling multiple users to edit documents simultaneously while seeing each other’s changes as they happen.

Why we needed this change

Project teams work in increasingly distributed and asynchronous ways. Whether you are brainstorming ideas, drafting project requirements, writing status reports or planning the next phase of work, collaboration is at the heart of what makes projects successful. However, traditional document editing workflows often create friction: files are duplicated, versions become out of sync, and team members struggle to know which version is the most current. Parallel editing leads to conflicts, data loss and frustration.

At OpenProject, we’re always trying to find ways to help our users communicate and collaborate in better ways. We believe teams want to work together in real time, see who else is contributing and have confidence that their edits won’t be lost or overwritten. This is precisely why we worked on upgrades to the Documents module.

Important 

Please note that the changes outlined in this article are planned for release in version 17.0, which is currently scheduled for January 14, 2026.

Real-time collaboration in OpenProject

The redesigned Documents module brings true real-time collaboration to OpenProject. When you open a document, you can see who else is actively editing it. Their cursors appear on the page, showing exactly where they are and what changes they are making, as they type.

Real-time collaboration is not simply about being able to see other users’ changes. It’s also about removing the barriers that slow teams down: no more waiting for someone to finish editing before you can make your contribution, no more merging conflicting versions, no more hunting through email attachments or shared drives to find the latest version of a document. The most current document is always in one place, and everyone works from the same source of truth.

What’s new in Documents

The new Documents module represents both a significant user experience improvement and a fundamental technological shift:

Real-time collaborative editing: Multiple users can edit the same document simultaneously. You see who’s online, where their cursors are, and what they’re changing in real time. Complex conflict management happens automatically in the background, ensuring that no one’s edits are lost.

Modern rich text editor: Documents now uses BlockNote, a modern open source rich text editor that makes writing and formatting simple and intuitive. Adding rich content like images, videos, audio files, or code blocks is straightforward.

Dynamic work package references: You can now include references to work packages directly within documents using the /op or /workpackage commands. These references update dynamically, so if the name, status or type of a work package changes, these are reflected automatically in the document. This also makes it easy to link to features or reference bugs without manually copying and pasting information that might become outdated.

File attachments: Attach files to any document to provide additional context, supporting materials, or related resources. Everything stays organized in one place.

Improved design and usability: The entire interface has been redesigned with a focus on clarity and ease of use, with a particular focus on providing a distraction-free editing experience.

Take a look at this short preview Gif that shows the features listed above:

Preview for OpenProject 17.0: Four active editors in the Documents module, adding a heart image to the document, linking work packages and collaboratively writing and editing text.

Technical foundations

Making real-time collaboration possible required substantial work on the technical foundation of the Documents module. We’ve adopted two powerful open source technologies: BlockNote as our rich text editor and Hocuspocus as our real-time collaboration toolkit.

BlockNote provides the editing experience users interact with directly. It’s extensible, modern and designed with collaboration in mind. One particularly exciting aspect of using BlockNote is that our new work package reference components are built to be generic and reusable, such that other tools that use BlockNote can also benefit from these same components. For example, Docs, part of France’s LaSuite and Germany’s openDesk, is based on BlockNote. XWiki is also testing an integration with BlockNote, which will allow users of these tools to call our BlockNote extension add dynamic links to OpenProject work packages in their text. The combination of XWiki’s knowledge management platform and OpenProject’s work management capabilities is especially potent as a replacement for Atlassian’s Jira-Confluence package. Such integrations create a more consistent experience for users working across different tools in their digital workspace.

Hocuspocus handles the complex real-time synchronization and conflict resolution that happens behind the scenes. When multiple users are editing simultaneously, Hocuspocus ensures that changes are merged correctly, no edits are lost and that the editing experience remains smooth.

These technologies form a solid foundation for collaborative editing in the Documentions module today, and potentially across other areas of OpenProject in the future.

Looking ahead

The new Documents module is the first step in a larger vision for real-time collaboration in OpenProject. However, it’s also a test bed. We’re using Documents to refine our technology, test our infrastructure and learn how our users collaborate in practice.

Once the technology is stable and we’ve gathered real-world experience, we plan to introduce real-time collaboration in other areas of OpenProject where it can bring value. Work packages are an obvious next candidate. Our goal is to make it possible for you to see your colleagues editing work package descriptions or updating custom fields in real time, with the same experience you now have in Documents.

How to access the new Documents module

For Cloud users: If have an OpenProject Cloud subscription, the new Documents module is available starting with version 17.0. You don’t need to do anything. Hocuspocus and all other dependencies are already installed and configured. Simply ensure the Documents module is enabled for each project where you want to use it, and you can start collaborating immediately.

For on-premises users: How you access the new Documents depends on your installation type:

• Containerized installations (Kubernetes, Docker, or Helm charts): Everything works out of the box. Hocuspocus is automatically installed and configured for you and real-time collaboration is enabled by default.

• Package-based installations (DEB/RPM packages): You’ll need to manually install dependencies such as Hocuspocus and configure them to enable real-time collaboration. We’re preparing an admin guide to walk you through this process.

What happens to existing documents

All documents created before version 17.0 remain accessible exactly as they were, using the CKEditor-based text editor. These documents do not support real-time collaboration, but they’re fully functional and unchanged. You can continue to use them as you always have.

Starting with version 17.0, all newly created documents use BlockNote and support real-time collaboration (if real-time collaboration is properly configured and enabled). This means you’ll have both old-style and new-style documents coexisting in your OpenProject instance. Older documents will have a ‘Legacy’ label on them for easy identification.

Important 

If real-time collaboration is enabled and users create new documents, but real-time collaboration is subsequently disabled (either manually or due to issues reaching the Hocuspocus server), those documents will no longer be accessible. We are aware this can lead to loss of access to data, so we strongly recommend that you not disable real-time collaboration after it has been enabled.

If real-time collaboration is not enabled—for example, because Hocuspocus is not available—new documents will continue to use the old style with CKEditor, without real-time collaboration features.

Your feedback

There is of course still a lot of work to do before we have real-time collaboration across all of OpenProject. We would really appreciate your help in getting us there.

Your feedback will help us understand what we’re doing right, what we can improve and what we should focus on. Does having real-time editing in OpenProject change the way you work? Will you use this in your own projects? What are ways we can improve it?

As an open source company, we develop in the open and value input from our user Community. If you have thoughts about the new Documents module, questions about how it works, or ideas for how we can make it even better, we’d love to hear from you. Join our Community instance and share your feedback.

Credits

We would like to thank the team behind BlockNote — Yousef El-Dardiry, Nick Perez, and Matthew Lipski — for creating such an excellent open source rich text editor. Thanks as well to the team behind Hocuspocus for providing the robust real-time collaboration infrastructure that makes this possible.

We’d also like to thank the design, development and QA teams at OpenProject for their hard work in making all this possible.