Sooner or later, many SaaS products find that their most important data is not in their database. It is in Word documents: the engagement letter, the audit working paper, the policy out for review, the contract waiting for signature. Users want to open those documents, edit them, comment on them and track changes to them without leaving the product. Downloading a file, editing it on the desktop and uploading it again is a poor substitute.
There are broadly three ways to build that experience:
- Embed Microsoft’s own editor. You can do this through the WOPI protocol and the Microsoft 365 Cloud Storage Partner Program, or through SharePoint Embedded.
- Convert the document. A generic rich-text editor edits a converted copy, which is converted back to DOCX afterwards.
- Embed an editor that works on the DOCX format itself, inside your own web application.
SuperDoc is in the third category.
McKenna Consultants has been implementing SuperDoc for a SaaS company in the audit sector. This article covers:
- what SuperDoc is and how it works under the hood
- what it gives you, and what it leaves to you
- how its licensing works, which matters more than usual here
It is written for product owners and engineering leads deciding whether a SuperDoc DOCX editor belongs in their architecture.
What Is SuperDoc?
SuperDoc’s documentation puts it plainly:
“SuperDoc is a document editor you embed in your web application. It lets people open, edit, and export DOCX files, using the document’s underlying format as the foundation for editing.”
It is developed by Harbour Enterprises, Inc., which trades as SuperDoc. It is published on npm as the superdoc package, and its source is on GitHub in the superdoc/docx-editor repository. The company describes the product as a “DOCX editor and Agent SDK”: a browser editor for people, plus tooling that lets services and AI agents read and change the same documents in code.
Three properties define it, and they are worth understanding before you look at features.
DOCX is the working format. SuperDoc does not import a Word document into some other representation and export a lookalike at the end. In its own words, “SuperDoc reads the OOXML package into editable document state. The browser renders a view of that state; edits update it, and export writes the changes back into the OOXML package.”
It runs inside your application. “The Editor runs in the browser and needs no SuperDoc server to render or edit a document.” The documentation is explicit about where responsibility sits: “Your application decides where documents come from, who can access them, and where changes are saved.”
It is programmable. People edit through the interface. Application code can read and change the same open document through the Document API. Supported headless clients (Node.js, Python and a command-line tool) use the same document engine and the same operation contract.
Why Native DOCX Editing Matters
A Word document is more than its text. It is an Office Open XML (OOXML) package: a ZIP archive of XML parts, relationships and media. Those parts carry the styles, section and page setup, headers and footers, numbering, comments and tracked changes.
The traditional way to put “Word editing” into a web application is to convert that package into HTML, let a rich-text editor work on the HTML, then build a new DOCX from the result. SuperDoc’s documentation names the weakness of that approach:
“When an editor converts DOCX into HTML or another editing format, it has to translate between two document models. Details that the editing model cannot represent may be changed or dropped when the DOCX is rebuilt for export.”
For a marketing page or a knowledge-base article, a little loss in translation may not matter. For a product whose documents are records, such as audit evidence, contracts or regulated policies, it matters a great deal. Suppose a reviewer’s tracked change or comment survives inside your product, but is missing or altered when the client opens the file in Microsoft Word. Your product has then broken the record it exists to keep. In our view, this is the most important reason to consider an OOXML-native editor: round-trip fidelity is part of the product’s integrity, not a cosmetic nicety.
Fidelity is still something you test, not something you assume. SuperDoc’s own upgrade guidance recommends exporting an edited document and checking it: “Reopen the result in Microsoft Word or another DOCX reader.” We recommend building a corpus of your users’ real documents early and running it on every upgrade. Your documents will exercise features no sample file does.
How SuperDoc Works
SuperDoc’s architecture documentation describes four stages that a document passes through:
- Open. “The engine parses content, styles, relationships, media, headers, footers, and the other OOXML parts into editable document state.”
- Render. “The layout engine paginates that state. The browser painter projects the resolved pages into DOM. The DOM is an output, not the document format.”
- Edit. “Editor input and headless operations update document state. The Document API defines queries, targets, mutations, and receipts.”
- Write. “Save and export write the changes back into the OOXML package instead of rebuilding a DOCX from HTML.”
SuperDoc calls this “the no-conversion boundary: OOXML remains the source of document meaning from open through export.”
The practical consequence is that there are several ways to drive the same document, each suited to a different caller:
| Caller | SuperDoc surface | Typical use |
|---|---|---|
| A person | Browser Editor | Reading, editing and reviewing documents inside your product |
| A service or CI job | Node.js SDK, Python SDK, CLI | Batch processing, document generation, automated review steps |
| An AI agent | SDK agent tools, MCP server | Instruction-driven edits, AI-proposed changes |
| Any code | Document API | Structured reads, mutations and receipts |
The Document API is the common thread. SuperDoc describes it as “an operation contract, not another runtime”: the browser editor and the supported headless clients “expose the same operation names and data shapes.” For an integrator, that means one mental model for both the interactive and the automated sides of a document workflow.
What You Get Out of the Box
SuperDoc’s feature set is aimed squarely at review-heavy document workflows.
Document modes. The editor has three modes. editing changes text directly, and is the default. suggesting turns each edit into a tracked change for someone else to review. viewing disables editing. The documentation adds a caveat that architects should take seriously: “Modes change Editor behavior in the browser. They do not decide who can open or save the document.”
Tracked changes and comments that stay in the DOCX. Reviewers can propose, accept and reject changes. Undecided changes are kept in the saved file, and comment threads can be created, replied to and resolved “that stay in the DOCX”. The review state travels with the document rather than living only in your database.
Templates and fields. SuperDoc builds templating on Word content controls, which it describes as marking “a region of the document” and giving “it metadata your application can find”. It maps Word’s own content-control properties onto its API:
- Word’s Tag becomes
properties.tag. - Word’s Title becomes
properties.alias. - Each occurrence has its own
id.
A template prepared in Word can therefore be filled from your application data, and a field your application creates is visible as a normal content control when the file is opened in Word.
Real-time collaboration. Editors that join the same room see each other’s changes as they are made. A provider carries those changes between them. SuperDoc’s server guidance lists three provider types: Hocuspocus, y-websocket and Liveblocks.
Your interface or theirs. You can use SuperDoc’s built-in toolbar, context menu and comments UI, configure them, or replace them entirely. In the replacement case, SuperDoc keeps rendering the document canvas while your application renders the controls. There is a React wrapper, Vue bindings, and a plain JavaScript API for everything else.
Beyond the Browser: Automation and AI Agents
The “Agent SDK” half of SuperDoc’s description is not marketing garnish. The same engine is available as:
- a Node.js SDK (
@superdoc/sdk) - a Python SDK (
superdoc-sdk) - a command-line interface
- an MCP server that lets coding agents such as Claude Code, Claude Desktop, Cursor and Windsurf open, edit and save DOCX files
In SuperDoc’s words, “The MCP server and these SDKs run in a local or server process. They edit the document without mounting the Editor UI.”
For document-centric products, the most interesting pattern is AI as a proposer rather than an author. Because the Document API can create tracked changes as well as direct edits, a model’s proposed edit can land in the document as a tracked change that a person accepts or rejects. In regulated work, where a human must stand behind every word, this is the right shape for AI assistance in our view. The machine drafts, the professional decides, and the document records which was which.
SuperDoc’s own agent guidance makes the necessary point about verification: “A successful tool call means the operation ran. You still need to check that the edit matches your request.”
What SuperDoc Leaves to You
An embedded editor is a component, not a platform. Several responsibilities stay with your application, and they are where most of the integration effort goes.
Storage and access control. SuperDoc does not store your documents or decide who may open them. Its security guidance is blunt about the browser: “Document mode, disabled buttons, permission resolvers, read-only comments, and hidden review controls guide normal browser interaction. They do not enforce access against a user who controls the browser.” Read, write, export and collaboration permissions must be enforced on your servers.
Collaboration infrastructure. If you want real-time co-editing, you need a provider: either a server you run or a hosted service. SuperDoc’s example server “deliberately has no authentication or durable storage”. Before production, you need to authenticate connections, authorise each room, persist room updates, and define backup and recovery.
Telemetry decisions. This one is easy to miss. SuperDoc’s documentation states: “Telemetry is enabled by default. The browser Editor sends one document-open event when each DOCX becomes ready.”
That event carries the SuperDoc version, browser information including the page origin, and a document identifier with timestamps. It does not carry document content. The documentation says the payload “does not include the page path, query string, fragment, or document content”. For many customers, especially in regulated sectors, the right answer is a deliberate configuration choice: either a self-hosted endpoint or no telemetry at all.
import { SuperDoc } from 'superdoc';
import 'superdoc/style.css';
const superdoc = new SuperDoc({
selector: '#editor',
document: file,
telemetry: { enabled: false },
});
Every other data boundary. SuperDoc’s security guidance lists the places document content can leave the browser: “Collaboration providers transmit document updates and awareness data. Network proofing, AI, telemetry, logging, and upload handlers may transmit document content or metadata.” Your data protection assessment should cover each one you enable.
Licensing: Read This Before You Commit
SuperDoc’s licensing deserves the same attention as its architecture, because it affects whether and how you can ship.
SuperDoc is dual-licensed. Its documentation says the open-source code “is available under the GNU Affero General Public License v3.0”, and that “Proprietary and commercial deployments are available under the SuperDoc Commercial License.” Its guidance is to “Use the open-source license when your application can meet the AGPLv3 requirements.”
The AGPL has a network clause. Section 13 of the AGPLv3 (“Remote Network Interaction”) requires that, if you modify the program, your modified version “must prominently offer all users interacting with it remotely through a computer network … an opportunity to receive the Corresponding Source of your version”. For a proprietary SaaS product, this is why the commercial-licence conversation usually happens early. How the AGPL applies to your particular product is a question for your legal advisers, not for a blog post.
The DOCX engine is licensed separately. This is the detail most likely to surprise a team that remembers SuperDoc as “the open-source DOCX editor”. The current major version depends on a separately published package, @superdoc/docx-engine, and SuperDoc’s licence for it is unambiguous: “DOCX Engine, published as @superdoc/docx-engine, is proprietary software and is not open source.” The licence allows the engine to be used “solely as a dependency of SuperDoc”. Without a separate agreement, permitted uses are those allowed under the AGPLv3. Production or commercial use is otherwise governed by your agreement with SuperDoc. The licence also restricts reverse engineering the engine, or using it to build or assist a competing product, including with AI tools.
None of this is unusual for a commercially backed component. But it means your procurement and legal review should read both licences, the AGPLv3 and the DOCX Engine licence, alongside any commercial agreement you sign.
Security Posture
For buyers in regulated sectors, SuperDoc’s deployment model is a strong argument. Its trust documentation describes the Editor as “self-hosted. Your documents stay on your infrastructure. The SuperDoc team cannot access your content.” The DOCX Engine licence says the same: the engine “is self-hosted by Customer”, and SuperDoc “does not host Customer’s production deployment”.
SuperDoc also states that it “is SOC 2 Type II certified”. It says its hosted APIs, which are separate from the self-hosted editor, “do not persist document data”. As with any supplier claim, ask for the report itself as part of your due diligence.
Where SuperDoc Fits Alongside WOPI and SharePoint Embedded
SuperDoc is not the only way to put Word editing into a product, and it is not always the right one.
WOPI with Office for the web gives users Microsoft’s own Word, Excel and PowerPoint editors, hosted by Microsoft, editing files your service stores. Access comes through the Microsoft 365 Cloud Storage Partner Program. Microsoft describes the programme as being “for independent software vendors whose business is cloud storage”, and Microsoft’s documentation states that “To edit documents, users require an Microsoft 365 license.” Read our introduction to what WOPI is for the background.
SharePoint Embedded is Microsoft’s API-only platform for building applications on Microsoft 365 document storage. We have covered what SharePoint Embedded is and how it compares with WOPI in detail.
SuperDoc is an editor component you own and host, with no Microsoft service in the editing path. It is a DOCX editor: if your users also need to edit spreadsheets and presentations in the browser, that is outside what it is for.
In our view, SuperDoc is a strong fit when several of these hold:
- Your documents are Word documents, and the DOCX file is the system of record.
- You need control over the editing interface and the review workflow, not just a window onto someone else’s.
- Data locality matters, and you want the editor to run on infrastructure you control.
- You want automated or AI-assisted edits to go through the same engine your users edit in.
- Not all of your users hold Microsoft 365 licences, or you do not want editing to depend on them.
The Microsoft routes are stronger when users expect genuine Word, need Excel and PowerPoint too, or depend on Office add-ins and the wider Microsoft 365 ecosystem.
How McKenna Consultants Can Help
McKenna Consultants has been building custom software since 2004, and Microsoft document integration is one of our core competences. We have implemented WOPI in .NET Framework, .NET Core, Java, Node and PHP. We have also been implementing SuperDoc for a SaaS company in the audit and compliance sector. Few teams have worked with both the Microsoft and the non-Microsoft approaches to embedded document editing, which is why we can give an honest comparison.
We help SaaS vendors and enterprises:
- choose between SuperDoc, WOPI and SharePoint Embedded for their requirements and constraints
- design the surrounding architecture: storage, authorisation, collaboration servers, telemetry and data boundaries
- build custom editing interfaces and review workflows on SuperDoc’s Document API
- design AI-assisted document workflows that keep a human in control
- build a document-fidelity test corpus so that every upgrade is a measured change rather than a leap of faith
If you are evaluating embedded document editing for your product, talk to our team or read more about our systems integration and WOPI integration services.
Sources
- SuperDoc documentation — SuperDoc Editor overview: definition of SuperDoc, the conversion problem, browser execution, and AGPLv3/commercial availability.
- SuperDoc documentation — How SuperDoc works: the open, render, edit and write stages, the “no-conversion boundary”, execution surfaces, and the Document API as an operation contract.
- SuperDoc documentation — Choose a document mode: editing, suggesting and viewing modes.
- SuperDoc documentation — Templates and fields: content controls, and the Tag, Title and ID mapping to Word properties.
- SuperDoc documentation — Run a collaboration server: supported provider types and production responsibilities.
- SuperDoc documentation — Agents and automation overview: Node.js and Python SDKs, CLI, MCP server, and verification of agent edits.
- SuperDoc documentation — Configure telemetry: telemetry defaults, payload and opt-out.
- SuperDoc documentation — Secure browser document workflows: data boundaries and server-side enforcement.
- SuperDoc documentation — Licensing: AGPLv3 and SuperDoc Commercial License.
- SuperDoc documentation — SuperDoc DOCX Engine Proprietary License: proprietary status, authorised use, restrictions and self-hosting of
@superdoc/docx-engine. - SuperDoc documentation — Trust & Security: SOC 2 Type II statement and self-hosted deployment model.
- SuperDoc documentation — Migrate from v1: guidance to verify exported documents in Microsoft Word or another DOCX reader.
- Free Software Foundation — GNU Affero General Public License v3.0: Section 13, Remote Network Interaction.
- Microsoft Learn — Microsoft 365 for the web (CSPP): CSPP is “for independent software vendors whose business is cloud storage”.
- Microsoft Learn — CSPP integration overview: “To edit documents, users require an Microsoft 365 license.”
