SuperDoc: a DOCX-native editor and Document API for browser and agent workflows

The problem SuperDoc targets: DOCX is a package, not a document tree

Most browser editors treat a document as one tree of nodes. A DOCX file is not that. It is a package of related XML parts, relationships and assets, and the visual result depends on pagination, section breaks, headers, footers and tables that live across those parts. The README states plainly that SuperDoc V1 used ProseMirror as its authoritative browser editing model, and that server use required a simulated browser DOM while collaboration needed a separate synchronization layer for the rest of the package.

SuperDoc V2 replaces that with an OOXML-backed document model. According to the README, it reads progressively, renders bounded windows, runs without a browser DOM, and synchronizes document content and package state through one collaboration model. The stated benefit is that edits write back to the XML without an HTML conversion step. That matters for anyone whose output has to reopen correctly in Word, because a round trip through HTML is where headers, footers and table geometry usually degrade.

The audience is narrow but real: teams building document review, contract redlining, proposal generation or agent pipelines where the file format is fixed as DOCX and the fidelity requirement is high. If your users only need formatted text in a web app, this is more machinery than the problem requires.

How the OOXML-backed model changes editing and collaboration

The mechanism described in the README is a document model backed by OOXML rather than an editor tree. The engine owns the underlying OOXML parts and relationships, and edits are expressed as supported document operations instead of raw XML manipulation. That is the same model exposed to agents: the README says agents use supported document operations rather than touching XML directly.

Two consequences follow from the architecture as described. First, the editor needs no server of its own; the README states browser editing covers view, edit, suggest, comment, track changes and collaboration with Yjs. Second, because the model is not tied to a browser DOM, the same Document API is offered through a Node.js SDK, a Python SDK, a CLI and an MCP server. The README frames this as one Document API for querying, targeting, changing and inspecting receipts.

The repository layout supports that claim about scope: packages/ holds the workspace packages, and examples/ contains directories for collaboration, content-controls, custom-ui, document-modes, proofing, react, sdk-batch, search, sveltekit, vanilla and version-history. The presence of a search example and an sdk-batch example suggests the API is meant to be driven programmatically, not only through the UI.

The trade-off is that an OOXML-backed model commits you to OOXML semantics. Anything that expects a generic content tree, such as a CMS body field or a markdown-first pipeline, does not map cleanly onto it.

Installing SuperDoc and mounting a first editor

The package is published on npm as superdoc. The README's quick start is a single install command:

npm install superdoc

SuperDoc mounts into elements you provide, so the page needs a container and a toolbar element before it runs. The README gives this markup:

<div id="superdoc-toolbar"></div>
<div id="superdoc"></div>

Then you import the stylesheet and the class, and construct an instance. The README's example passes a selector, a toolbar selector, a document path and a document mode:

import 'superdoc/style.css';
import { SuperDoc } from 'superdoc';

const superdoc = new SuperDoc({
  selector: '#superdoc',
  toolbar: '#superdoc-toolbar',
  document: '/sample.docx',
  documentMode: 'editing',
});

What you should see is the DOCX rendered in the container with the toolbar above it. The README states that document accepts a URL, a File, or a Blob, and that omitting it starts with a blank DOCX. The README points to docs.superdoc.dev for next steps and to a React quick start page. If you are working in another framework, the examples directory has react, sveltekit and vanilla entries, but the README itself does not walk through them.

Where SuperDoc is the wrong tool

The most concrete limitation is the licence, and it is not a footnote. SuperDoc is AGPL-3.0 for open source use, and the README says a commercial licence is available for proprietary deployments. AGPL-3.0 carries a network clause, so a hosted service built on this code has obligations that a permissive licence would not impose. Teams that cannot ship copyleft code, or cannot take on the network clause, should treat the commercial licence as part of the cost of adoption rather than an optional upgrade. The README does not state pricing or terms; it links to a contact page.

A second limitation is scope. SuperDoc is built directly on OOXML, and the README presents that as the point. If your content is not DOCX, the fidelity machinery is overhead. A markdown editor or a generic rich-text editor will be smaller, faster to integrate and easier to reason about.

A third is that the README documents no rollback path for failed or unwanted edits. The repository includes an examples/version-history directory, which implies version history is at least demonstrated, but the README does not describe an undo or revert API, and it does not document what happens when a write-back to XML fails partway through a package with many parts. Anyone building on this should test that failure path directly rather than assume it is handled.

SuperDoc compared with ProseMirror-based DOCX editing

The most useful comparison is with the approach SuperDoc itself moved away from, which the README describes: ProseMirror as the authoritative browser editing model. In that design, the editor tree is the source of truth and DOCX is an import and export format. The advantage is a mature editing model with a large ecosystem of plugins and a well-understood transaction system. The cost is the conversion boundary. Every import and export is a translation, and translation is where pagination, section properties and package relationships tend to be approximated rather than preserved.

SuperDoc's difference in approach is that the OOXML-backed model is the source of truth, so there is no HTML conversion step in the edit path. That should reduce fidelity loss, and it is also why the same API can run server-side without a simulated browser DOM. The price is that you are not on the ProseMirror plugin ecosystem, and the editor's behaviour is bounded by what the OOXML model supports.

A second alternative is to skip the editor entirely and manipulate DOCX with a library that reads and writes the package, then convert to PDF for display. That works when users only need to read or generate documents, and it avoids shipping an editor bundle. It stops working the moment someone needs to track changes or comment inside the file.

Maintenance, releases and the AGPL-3.0 decision

The repository is not archived, and the last push was on 2026-09-15. Recent releases are v2.12.0 on 2026-09-04, v2.13.0 on 2026-09-08 and v2.14.0 on 2026-09-11, which is a cadence of roughly one release per week across that window. The package manager is pinned in package.json as pnpm@11.24.0, and the root package is private with the monorepo licence field set to AGPL-3.0.

The upgrade cost is mostly the monorepo's own complexity rather than the published package. The root scripts include a rebuild:types target that filters across @superdoc/common, @superdoc/word-layout, @superdoc/contracts, @superdoc/dom-contract, @superdoc/layout-resolved, @superdoc/geometry-utils, @superdoc/style-engine, @superdoc/measuring-dom, @superdoc/layout-engine and @superdoc/layout-bridge before building @superdoc/painter-dom. If you consume the published superdoc package you never run that, but if you vendor the source or patch a layout bug, you are building that chain.

On licence implications, and this is not legal advice: AGPL-3.0 applies to the code, and the README offers a commercial licence for proprietary deployments. The practical question for a team is whether their use is distribution, network service, or internal. Internal tools and open source projects sit differently from a hosted product with paying users. The repository also ships CLA.md and THIRD_PARTY_LICENSES.md at the top level, so contribution terms and bundled dependencies are documented if you need to check them.

Editorial conclusion

Adopt SuperDoc if you need DOCX pagination, headers, footers and tables to survive editing, and if your product can live with AGPL-3.0 or you intend to buy the commercial licence. Do not adopt it if you need a general rich-text editor for HTML content, or if a copyleft dependency in your frontend bundle is a blocker you cannot resolve. Before committing, verify three things: whether your deployment triggers the AGPL network clause, whether the Python SDK and MCP server cover the operations your agent needs, and what the commercial licence costs for your seat count. The README documents the editor, the SDKs and the CLI, but it does not document rollback behaviour for failed edits, and the repository ships a version-history example rather than a documented rollback API.

Frequently asked questions

Official sources

1. License: AGPL-3.0
2. Project website
3. README
4. Releases
5. superdoc/docx-editor on GitHub