How Do I Upgrade SuperDoc v1 to v2? A Practical Migration Guide

There is a short answer to the question in the title, and SuperDoc’s own migration guide gives it:

“If your v1 application mounts SuperDoc from the package root, waits for readiness, and exports through the same instance, most of that integration remains valid. The migration is mainly about selecting the v2 package and removing dependencies on v1 internals.”

The long answer depends on how far your application reached beyond that root integration. That might be custom toolbars, programmatic edits through ProseMirror state, custom extensions, DOM selectors, or real-time collaboration. Each of these moves to a different place in v2, and some have no direct equivalent at all.

This guide sets out a practical sequence to upgrade SuperDoc v1 to v2 without putting your users’ documents at risk. It is built on SuperDoc’s published migration documentation, and written by a team currently implementing SuperDoc for a SaaS company in the audit sector. If you need the background first, read What Is SuperDoc? and What’s New in SuperDoc v2?

Before You Touch the Code

Four pieces of preparation make the rest of the migration safer and faster.

1. Put the licence in front of the right people

v2 is not only a code change. The superdoc v2 package depends on @superdoc/docx-engine, and SuperDoc’s licence for that package states: “DOCX Engine, published as @superdoc/docx-engine, is proprietary software and is not open source.”

Without a separate agreement with SuperDoc, the engine may be used as a dependency of SuperDoc for uses permitted under the AGPLv3. Production and commercial use is otherwise governed by your agreement with the company. If your organisation adopted v1 under its AGPLv3 terms, your legal and procurement teams should review the DOCX Engine licence before you ship v2. This has the longest lead time of anything in this guide, so start it first. (This is not legal advice.)

2. Build a document corpus and a v1 baseline

Collect a representative set of your users’ real documents, with any sensitive content suitably anonymised. Include the awkward ones:

• long documents
• heavily tracked documents
• documents with comments, content controls, complex numbering, fields, footnotes, headers and footers
• documents produced by your own templates

Open, edit and export each one in your current v1 integration, and keep the outputs. This is your baseline. Sample files exercise a small part of the format; your users’ documents exercise the rest, and that is where an upgrade can quietly regress.

3. Run v1 and v2 side by side

SuperDoc’s guidance is explicit: “Keep v1 and v2 on separate branches or deployments while comparing the same input documents. A package upgrade should remain easy to reverse until the documents that matter to your product complete this round trip.”

The 1.x line continued to receive releases after v2 shipped (1.46.0 on 5 August and 1.46.3 on 26 August), so staying on v1 while you migrate is a practical option. Pin your v1 version exactly while the v2 branch matures.

4. Inventory what your integration actually uses

SuperDoc publishes a machine-readable migration catalogue alongside its “Removed in v2” reference. Its migration guide also includes a prompt for teams using an AI coding agent. The prompt asks the agent to inspect the project, without changing code, and report five things:

1. “Removed imports and package subpaths”
2. “Any direct editor.* access, including commands, state, view, chain(), helpers, comments, presentationEditor, and on()”
3. “Legacy configuration and collaboration usage”
4. “Custom UI, extensions, and DOM selectors that require redesign”
5. “Synchronous Document API reads such as doc.extract(), doc.getMarkdown(), and doc.selection.current(), which the browser resolves as Promises”

Whether you use an agent or a code search, those five categories are the right inventory. They also tell you how big the migration is.

Step 1: Size the Migration

Here is our rule of thumb for effort, based on what the inventory finds:

Step 2: Install v2 and Fix the Packages

The core package name does not change. Upgrade superdoc to the current release. The first stable v2 release is 2.3.0: version numbers 2.1 and 2.2 on that npm name belong to an unrelated package from 2016–2017. Do not add version switches to your configuration. The migration guide says: “Do not add editorVersion, v2, or v2Integration to the editor configuration. The v2 package always runs the v2 DOCX engine and has no runtime fallback to v1.”

If you use the React wrapper, it has moved to a new npm scope:

npm uninstall @superdoc-dev/react
npm install superdoc @superdoc/react

The guide adds: “@superdoc/react declares the compatible superdoc release. Install the wrapper by package name instead of trying to match its version number to the editor version.”

Next, deal with removed package subpaths. These fail at module resolution, so your build will find them for you:

One firm rule: do not “fix” a removed import by reaching for an internal package. SuperDoc warns that packages such as @superdoc/v2-host, @superdoc/headless and @superdoc/document-api-v2-adapter “are implementation details, not customer integration surfaces.”

Step 3: Keep the Root Integration and Respect Readiness

The good news is that the outer shape of an integration survives. The editor class is still SuperDoc from superdoc, and the styles are still superdoc/style.css. You still pass a File, Blob or URL as document, wait for onReady, change modes with setDocumentMode(), export with export() and clean up with destroy():

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

const superdoc = new SuperDoc({
  selector: '#editor',
  document: file,
  onReady: ({ superdoc }) => {
    superdoc.setDocumentMode('editing');
  },
});

The behavioural change is readiness. “V2 opens and renders the DOCX progressively, so readiness is the public boundary for starting product interaction.” Audit any code that touches the document from onEditorCreate or other early hooks, and move it behind onReady.

Step 4: Replace Editor Internals with the Document API

This is usually the largest body of work. In v1, reading the document often meant reaching into ProseMirror:

// v1
const text = superdoc.activeEditor.state.doc.textContent;

In v2, reads and mutations go through the Document API on the active editor, and in the browser they return Promises:

// v2
const doc = superdoc.activeEditor?.doc;
if (!doc) throw new Error('The active document is unavailable.');
const text = await doc.getText({});

Three pitfalls catch teams out.

Silent failures. SuperDoc’s “Removed in v2” reference explains that v2 exposes commands, state and view on the editor facade as null rather than removing them. A direct property access throws a generic null-property error that names your code rather than SuperDoc. Worse, “Optional chaining … turns the same mistake into a silent no-op that never errors at all.” Search for editor.state, editor.view, editor.commands and editor.chain explicitly. Do not rely on errors to find them.

Insertion location. v1’s tr.insertText(text) inserted at the caret. The v2 equivalent needs an explicit target. As SuperDoc’s guide puts it: “A targetless insert appends at the end of the document.” Capture the selection target first:

const doc = superdoc.activeEditor?.doc;
if (!doc) throw new Error('The active document is unavailable.');

const selection = await doc.selection.current({});
if (!selection.selectionTarget) {
  throw new Error('No selection target; refusing to append by accident.');
}
await doc.insert({ value: text, target: selection.selectionTarget });

Synchronous assumptions. Reads such as doc.getMarkdown() and doc.selection.current() resolve as Promises in the browser. Code that expected a value receives a Promise, so reads look empty and downstream properties are undefined. Add await everywhere you call the Document API from browser code.

Step 5: Rebuild Custom UI on the Controller

A v1 custom toolbar is not restored by changing its import path. The guide says: “Bind the application UI to the controller owned by the ready SuperDoc instance, then move each control’s state and execution to a public command handle.”

In React, that means:

• rendering SuperDocUIProvider in an ancestor of your controls
• binding the instance with useSetSuperDoc() from onReady
• reading each control’s active, enabled and value from useSuperDocCommand(id)
• running actions with superdoc.ui.commands.executeAsync(id, payload)

Vue has equivalent composables in superdoc/ui/vue. Note the guide’s warning about lifecycle: “Do not create a controller for every render, tab, or document. One SuperDoc instance owns one stable controller.”

Navigation moves to the controller too. If your v1 code retrieved the renderer runtime with getDocumentRuntimeForDocument(), expect errors such as “DocumentRuntime is not available” in v2. Use the feature-specific methods instead:

• superdoc.ui.trackChanges.scrollTo(changeId) for a tracked change
• superdoc.ui.comments.scrollTo(commentId) for a comment
• superdoc.ui.contentControls.scrollIntoView({ id }) for a content control

The same applies to DOM selectors. v2 virtualises pages, so an element for a tracked change or comment on an unpainted page may not exist. Code that worked on a five-page test document can fail on a fifty-page production one.

Step 6: Remodel Extensions and Custom Data

v2 extensions are written with defineSuperDocExtension, and they are deliberately narrower than v1’s. According to SuperDoc’s reference, “They do not receive ProseMirror state, custom schema, or mutable DOM, so extensions that defined custom nodes or marks may have no v2 equivalent.”

If your v1 integration stored application data in custom nodes or marks, the v2 approach is to store it in structures Word itself understands:

• Content controls (doc.contentControls) for structured regions people can edit.
• Anchored metadata (doc.metadata) for application JSON tied to a text range. It is stored as a hidden inline content control plus Custom XML.
• Custom XML parts (doc.customXml) for data not attached to text.
• Citations and fields (doc.citations, doc.fields) where Word should recognise the value.

v1 field annotations that served two purposes need a decision for each. SuperDoc’s migration reference splits them: citations backed by a source record move to doc.citations, and application-owned annotations move to anchored metadata. Its advice is to treat this “as remodelling rather than a rename”.

There is an upside to this work. Data stored in content controls and custom XML is standard OOXML, so it survives a trip through Microsoft Word, whereas data held in proprietary editor nodes did not.

Step 7: Treat Collaboration as Its Own Project

If your product uses real-time collaboration, do not fold it into the main upgrade. The migration guide is unambiguous: “V2 collaboration rooms use a different document format and require a separate migration. Do not connect a v2 editor directly to an existing v1 collaboration room.”

Two further changes affect the design:

• SuperDoc owns the provider. v1 applications supplied an external Yjs document and provider. v2 takes a supported provider target and manages the connection itself, so do not port the external pair directly. The v2 package declares optional support for Hocuspocus and Liveblocks.
• Room migration tooling is maturing. The v2 package ships a superdoc/collaboration-upgrade-engine entry point. The 2.13.0 release notes record fixes so that “DOCX documents maintain full formatting and metadata through v1-to-v2 room upgrades”. Follow SuperDoc’s current collaboration documentation for the procedure, and rehearse it on copies of real rooms before you touch production.

Our recommended shape is a planned cut-over:

1. Choose a window.
2. Stop new v1 sessions.
3. Persist each room’s final state to DOCX.
4. Either upgrade the rooms or initialise fresh v2 rooms from those DOCX files.
5. Admit users to v2 only once each room is verified.

Keep the v1 deployment available until you are sure you will not need it.

Step 8: Re-check the Browser Boundary

v2 runs parts of its engine in module workers, which brings some deployment details.

• Split-origin bundles. If your JavaScript is served from a different origin from your application, copy v2’s three worker assets (document, collaboration and review-index) to your application’s origin, and pass their URLs in workerUrls.
• Content Security Policy. Allow the workers and connections your deployment needs. If your policy requires nonces for style elements, SuperDoc accepts a cspNonce for its runtime styles.
• Telemetry. SuperDoc’s browser editor sends telemetry by default: one document-open event per document. The payload is metadata, not content. Make an explicit decision to disable it or point it at an approved endpoint, and record that decision.

Step 9: Prove It with a Round Trip

SuperDoc’s guide recommends verifying “the smallest complete path” before migrating advanced UI or automation:

1. “Open a representative DOCX in v2.”
2. “Wait for onReady.”
3. “Make one direct or tracked edit.”
4. “Export the document with SuperDoc.export().”
5. “Reopen the result in Microsoft Word or another DOCX reader.”
6. “Confirm the edited content, formatting, comments, and tracked changes still match the intended document state.”

Then scale that check to your corpus. For each document, compare the v2 export with your v1 baseline and with the original:

• content and formatting
• tracked changes (author, date and type)
• comment threads and their anchors
• content controls and their tags
• headers, footers, numbering and fields

Automate whatever you can, then have someone who knows the documents review the rest in Word. In regulated workflows, that review is evidence. Keep it.

A Sensible Migration Sequence

Pulling this together, here is the order we recommend:

1. Start the licensing review.
2. Build the document corpus and capture the v1 baseline.
3. Create a v2 branch or deployment, leaving v1 pinned and running.
4. Fix packages and removed imports until the build is clean.
5. Prove a single round trip with a representative document.
6. Migrate programmatic reads and edits to the Document API.
7. Rebuild custom UI and navigation on superdoc.ui.
8. Remodel extensions and custom data into Word-native structures.
9. Plan and rehearse the collaboration migration separately.
10. Roll out in stages, run the full corpus at each stage, and keep the route back to v1 open until you no longer need it.

Finally, pin exact versions once you are on v2. The 2.x line has been releasing quickly: twelve minor versions between 2.3.0 on 28 July and 2.14.0 on 11 September. Every upgrade should go through your corpus before it reaches users.

How McKenna Consultants Can Help

McKenna Consultants is implementing SuperDoc for a SaaS company in the audit and compliance sector, and we have been building custom software since 2004. We can:

• run the inventory and sizing exercise on your codebase
• build your document-fidelity corpus and the automation around it
• migrate custom UI, automation and extensions to the v2 APIs
• plan a collaboration cut-over that keeps your users’ documents safe

If you are planning a SuperDoc v2 upgrade, contact our team or read more about our systems integration work.

Sources

• SuperDoc documentation — Migrate from v1: the root integration that remains valid, package names and the React wrapper move, removed subpaths, internal packages, readiness, the Document API examples, targetless insertion, custom toolbar migration, navigation, collaboration room compatibility, worker assets, the AI-agent inventory prompt, and the round-trip verification steps.
• SuperDoc documentation — Removed in v2: null editor internals and optional-chaining no-ops, the v2 extension model, and field annotation remodelling.
• SuperDoc documentation — Store application data in DOCX: content controls, anchored metadata, custom XML, citations and fields.
• SuperDoc documentation — SuperDoc DOCX Engine Proprietary License: proprietary status and authorised use of @superdoc/docx-engine.
• SuperDoc documentation — Secure browser document workflows: Content Security Policy and cspNonce.
• SuperDoc documentation — Configure telemetry: telemetry defaults and payload.
• SuperDoc on GitHub — 2.13.0 release notes: v1-to-v2 room upgrade fidelity.
• npm registry — superdoc package versions: release dates for 1.46.x and 2.3.0 to 2.14.0, the collaboration-upgrade-engine export, Hocuspocus and Liveblocks optional peers, and the unrelated 2.1 and 2.2 versions.