Overview

@docx-editor.dev/editor-api edits DOCX files through a supported subset of Word's JavaScript object model, including paragraphs, ranges, comments, and revisions. Use load() to queue reads and sync() to apply each batch atomically.

Run the API on a server over DOCX bytes or in the browser against an open editor. See Office.js compatibility for supported members and differences from Word.

npm install @docx-editor.dev/editor-api @docx-editor.dev/core

The API and editor adapters must share one resolved copy of the @docx-editor.dev/core peer dependency.

Guides by task

Start with Runtime and setup and Batching, loading, and errors.

Choose a host

Use the root entry for server jobs and /browser to edit an open editor. For shared documents, use DocxEditor.createCollaborative() with your collaboration session.

| Host | Save through | Requirements | | ------------- | ----------------- | ---------------------------------------------- | --- | --------- | | Server | runtime.save() | DOCX bytes and Node.js ^20.16.0 | | >=22.3.0 | | Browser | The owning editor | An attached core, React, or Vue editor | | Collaborative | runtime.save() | DOCX bytes and an EditorCollaborationSession |

Supply an author for comments, replies, and tracked edits. Browser review writes also require the Pro review module and an editable document. Capabilities describe host features; handle write errors from the call or sync().

See Runtime and setup for capabilities, parsing limits, and resource cleanup.

On a server

The server runtime is headless. It accepts bytes and returns bytes.

import { readFile, writeFile } from 'node:fs/promises';
import { DocxEditor } from '@docx-editor.dev/editor-api';

const runtime = await DocxEditor.createServer(await readFile('contract.docx'), {
  author: 'Review bot',
});
try {
  await runtime.run(async (context) => {
    const matches = context.document.body.search('$50k');
    matches.load('items');
    await context.sync(); // Read the matching ranges.

    for (const match of matches.items) match.insertText('$500k', 'Replace');
    await context.sync(); // one atomic batch: all of the writes, or none
  });
  await writeFile('contract.filled.docx', await runtime.save());
} finally {
  runtime.dispose();
}

createServer() finishes parsing before it resolves. Each save() returns a fresh byte array. To update an open editor from a detached server job, load the saved bytes into that editor.

Create tracked changes on a server

Set context.document.changeTrackingMode = 'TrackMineOnly' before calling range.insertText() or range.delete(). Configure an author when you create the runtime. The mode applies to that runtime and persists across run() calls.

Tracked edits support text within one paragraph, including table cells. Edits that touch pending revisions, structural edits, and formatting edits are rejected atomically. TrackAll is unsupported. Browser tracked writes require the Pro review module; the runtime setting does not change the editor UI mode.

A pending row insertion or deletion blocks tracked edits throughout that row, including other cells and nested tables.

For a complete example, see the server agent guide. To publish suggestions to a shared document, use DocxEditor.createCollaborative.

In the browser

Pass an open core, React, or Vue editor to createBrowser(). Edits use that editor's undo history.

import { DocxEditor } from '@docx-editor.dev/editor-api/browser';

const runtime = DocxEditor.createBrowser(editor, { author: 'Demo Reviewer' });
try {
  await runtime.run(async (context) => {
    const heading = context.document.body.paragraphs.getFirstOrNullObject();
    heading.load('text');
    await context.sync();

    if (!heading.isNullObject) heading.font.bold = true;
    await context.sync();
  });
} finally {
  runtime.dispose();
}

Dispose the runtime when you finish. Save browser edits through the owning editor.

Editing rules

• Load properties before reading them. Load a collection's items, sync, then load each item's properties.
• Batch independent writes. Each sync() commits all queued writes or none; earlier successful syncs remain committed.
• Sync after insertion before using the returned object.
• After editing a paragraph, search again before editing another target there. Ranges retain their original offsets.
• Keep proxies inside runtime.run(), or explicitly track and adopt them across runs.
• Handle errors by code. On StaleDocument, read again and reconsider the edit.

See Batching, loading, and errors for recovery and Text and ranges for batching limits.

Build an agent

Define application tools around individual document tasks. Validate inputs and return plain data from each runtime.run() callback. Use revisionTextView to choose whether reads include pending insertions. Keep chat UI, model calls, and collaboration transport in your application.

See Build a DOCX agent for a walkthrough, or the server agent guide for tracked edits and recovery.

License

This package uses the EigenPal Pro License. See pricing for license and support options.

Next steps

• Build a DOCX agent
• Office.js compatibility
• API reference