Do Microsoft Office Add-Ins Work with SuperDoc v2?

It is a natural question for any product team weighing up SuperDoc. Suppose the team has invested in a Word add-in that its customers use every day. Now it wants Word editing inside its own web application, and it would like the add-in to come along.

The short answer is no: Office add-ins do not run inside SuperDoc. Office add-ins are built to run inside Microsoft Office applications, and SuperDoc is not one. We found nothing in Microsoft’s documentation or SuperDoc’s that describes running an Office add-in inside a third-party editor.

The useful answer is longer. An add-in’s value is usually not tied to Office. It lies in the data it writes into documents, the business logic behind it, and the workflow it supports. Much of that carries over to SuperDoc v2, some of it directly through the DOCX file itself. This article explains why add-ins need Office, what does carry over, and how to design a product where a Word add-in and a SuperDoc-based web editor work on the same documents.

Why Office Add-Ins Need an Office Application

Microsoft describes the platform’s purpose clearly: “Use the Office Add-ins platform to build solutions that extend Office applications and interact with content in Office documents.” The add-in is a web application, but Office loads and runs it. Microsoft’s overview describes how:

“the application (for example, Excel), reads the add-in manifest and connects the add-in’s custom ribbon buttons and menu commands in the UI. When needed, it loads the add-in’s JavaScript and HTML code, which runs in the context of a browser or webview control in a sandbox.”

Where it runs is equally explicit: “Office Add-ins run in Office on the web, Windows, Mac, and iPad.”

The deeper reason is the API model. A Word add-in does not edit a file. It sends requests to the running Word application, which owns the document. Microsoft’s reference for the Word request context explains: “Since the Office add-in and the Word application run in two different processes, the request context is required to get access to the Word object model from the add-in.”

Every Word.run(async (context) => { … }) block, every context.sync(), every range.insertText() is a conversation with Word. Without Word on the other end, there is nobody to talk to.

You can see this from inside the add-in, too. Microsoft documents that when Office.js finds it is “running outside of an Office host application”, it initialises anyway and resolves “with null for both the host and platform”. Load your add-in’s page next to SuperDoc and Office.js will start. It simply has no Word to drive.

So the honest framing is not “does SuperDoc support add-ins?” It is “which parts of what our add-in does can SuperDoc do, and how do the two share documents?”

What Carries Over: the Document Itself

Add-ins often leave their most important work in the document. Word documents are Office Open XML packages, an open standard that, in Microsoft’s words, “can be freely implemented by multiple applications on different platforms”. Several of the places add-ins store data are standard OOXML structures that SuperDoc v2 reads and writes.

Content controls

Content controls are the workhorse of document-centric add-ins. Microsoft defines them as “bounded and potentially labeled regions in a document that serve as containers for specific types of content”. Add-ins use their tags as identifiers: “The tag can be used to identify a content control programmatically.”

SuperDoc v2 works with the same structures. Its templates guide maps Word’s content-control properties directly onto its API:

• Word’s Tag is properties.tag.
• Word’s Title is properties.alias.
• Each occurrence has an id.

In SuperDoc’s words, “Content controls are stored as w:sdt elements in the DOCX.” In practice, a clause, field or evidence reference that your add-in marks with a tagged content control in Word can be found by that tag in SuperDoc, and the reverse is also true.

Custom XML parts

For structured data that is not attached to visible text, add-ins can write custom XML parts. Microsoft’s guidance explains the appeal: “The Open XML .xlsx and .docx file formats let your add-in embed custom XML data in the Excel workbook or Word document. This data persists with the file, independent of the add-in.”

SuperDoc v2’s Document API includes custom XML operations, which its reference describes as “Raw read and write of custom XML parts in the OOXML package”. Data your add-in writes there can be read by your SuperDoc integration, and the reverse is also true, provided both agree on the XML namespace and schema.

What does not carry over

Two other add-in storage mechanisms deserve caution.

Add-in settings (Office.context.document.settings) are private by design. Microsoft says they are “stored in the host document as name/value pairs”, but “available only to the add-in that created them, and only from the document in which they are saved.” Do not build a cross-application contract on them. That is not what they are for.

Add-in parts in the package. Add-ins can also leave parts in the package. Microsoft documents that add-ins without add-in commands “are inserted into the document, and persist in that document”. It also documents how to make a task pane open automatically by adding “a webextension part” and “a taskpane part” to the file. These parts only mean something to Office. We have not found SuperDoc documentation on how they are treated when a document is edited and exported. If your documents carry them, include such documents in your test corpus and check that they survive a round trip.

Rebuilding Add-In Functionality on SuperDoc

When the requirement is “our add-in’s features, inside our web app”, you are rebuilding the add-in’s front end on a different editor API. The business logic does not need to change. Here is how the main Office.js concepts map onto SuperDoc v2, in our reading of both APIs:

• Its own UI. Word add-in: a task pane inside Office. SuperDoc v2: your application’s own UI beside the editor.
• Commands. Word add-in: add-in commands on the ribbon. SuperDoc v2: toolbar custom items, context-menu sections, or superdoc.ui.commands.register.
• Reading the selection. Word add-in: context.document.getSelection(). SuperDoc v2: doc.selection.current().
• Inserting or replacing text. Word add-in: range.insertText(…). SuperDoc v2: doc.insert(…) or doc.replace(…) with an explicit target.
• Marking a region. Word add-in: range.insertContentControl(), with a tag. SuperDoc v2: doc.contentControls, with properties.tag.
• Storing structured data. Word add-in: Word.CustomXmlPart. SuperDoc v2: doc.customXml.
• Proposing changes for review. Word add-in: edits with Word’s change tracking on. SuperDoc v2: mutations with changeMode: 'tracked', reviewed through doc.trackChanges.
• Reacting to the user. Word add-in: Office events. SuperDoc v2: superdoc.ui.selection.subscribe and extension mutation hooks.

Three differences matter more than the method names.

SuperDoc gives you more of the screen. A task pane is a narrow column inside someone else’s application. In SuperDoc, the editor is a component inside your application. Your interface can wrap around the document, drive it, and integrate with the rest of your product without the boundaries a task pane imposes.

Targets are explicit. SuperDoc’s Document API works by querying for a target, mutating it and checking a receipt. Its documentation warns that “A targetless insert appends at the end of the document,” so capture the selection or query result you mean to change before you change it.

Server-side reuse becomes possible. SuperDoc’s Document API is shared by the browser editor and its Node.js and Python SDKs. Logic that an add-in could only run while a user had the document open in Word can, with SuperDoc, also run as a server-side job against the same document model.

Designing for Both: One Product, Two Front Ends

Many products will not choose between a Word add-in and a SuperDoc editor. They will offer both: the add-in for users who live in desktop Word, and SuperDoc for in-app editing and review. In our view, three design principles make that work.

1. Share everything except the document layer. Office add-ins are web applications. Microsoft notes that they “are web applications that are displayed using iframes when running in Office on the web”. Your add-in’s components, state management and calls to your backend are ordinary web code.

Put a thin document-access interface between that code and the editor, with one implementation over Office.js and one over SuperDoc’s Document API. Then the bulk of the codebase serves both front ends. The business rules belong on your backend anyway.

2. Make the document the integration contract. Decide, and write down, the conventions both sides honour:

• the content-control tags and titles that mark fields and clauses
• the custom XML namespaces that hold structured data
• how tracked changes and comments should be attributed

Version the contract like an API. If the Word add-in and the SuperDoc integration agree on it, a document can move between them without either losing track of what it contains.

3. Test the round trip in both directions. Create documents in Word with the add-in, edit them in SuperDoc, and reopen them in Word. Then reverse the journey. Check that tags, custom XML, tracked changes and comments all survive. This is the only reliable way to know the contract holds on real documents.

If Add-Ins Must Run in the Browser

If customers need their existing add-ins to run, unmodified, inside your web product, the answer is Microsoft’s own editor rather than SuperDoc. Office for the web can run add-ins in a WOPI integration, but with conditions. Microsoft states that “By default, Add-ins are not enabled for users connecting to Microsoft 365 through a WOPI host.” They must be “either preinstalled or sideloaded”, and “only Add-ins with Add-in commands are supported.” Microsoft’s requirement-set documentation also cautions that “Office Add-ins may not be supported on all services that are members of the Office Cloud Storage Partner Program”.

We compared the two architectures in detail in How Does SuperDoc v2 Compare to CSPP WOPI? If running unmodified add-ins is a hard requirement, weigh it heavily in that decision.

How McKenna Consultants Can Help

McKenna Consultants builds Microsoft Office add-ins for Word, Excel and Outlook. Our published work includes a Word add-in alongside WOPI for Corcentric, and an Outlook add-in with WOPI for Workiro. We have written about building cross-platform Office add-ins from one codebase. We are also implementing SuperDoc for a SaaS company in the audit and compliance sector.

That combination is exactly what this problem needs. We can:

• audit what your add-in actually does and where its data lives in the document
• design the document contract both front ends will honour
• build the SuperDoc-based web experience alongside your existing add-in
• automate the round-trip testing that keeps the two in step

Talk to our team about bringing your add-in’s capabilities into your web application.

Sources

• Microsoft Learn — Office Add-ins platform overview: purpose of the platform, how the Office application loads add-ins, and supported platforms.
• Microsoft Learn — Word.RequestContext: add-ins and Word run in separate processes, with access to the Word object model through the request context.
• Microsoft Learn — Initialize your Office Add-in: Office.js behaviour outside an Office host application.
• Microsoft Learn — Browsers and webview controls used by Office Add-ins: add-ins as web applications in iframes in Office on the web.
• Microsoft Learn — Word.ContentControl: content controls and the tag property.
• Microsoft Learn — Word.CustomXmlPart and Persist add-in state and settings: custom XML data persisting with the file.
• Microsoft Learn — Office.Settings: add-in settings stored in the document and scoped to the add-in.
• Microsoft Learn — Automatically open a task pane with a document: add-ins persisting in documents, and the webextension and taskpane parts.
• Microsoft Learn — About the Open XML SDK: Open XML as an open standard.
• Microsoft Learn — Office Add-ins in WOPI integrations: conditions for add-ins with WOPI hosts.
• Microsoft Learn — Office client application and platform availability for Office Add-ins: CSPP caveat on add-in support.
• SuperDoc documentation — Templates and fields: Word Tag, Title and ID mapping; content controls stored as w:sdt.
• SuperDoc documentation — Custom XML operations: reading and writing custom XML parts.
• SuperDoc documentation — Store application data in DOCX: content controls, anchored metadata and custom XML.
• SuperDoc documentation — Migrate from v1 and Removed in v2: Document API targeting, command registration, toolbar and context-menu extension points, and selection subscriptions.
• SuperDoc documentation — How SuperDoc works: shared Document API across the browser editor and headless SDKs.