# SuperDoc: Full Context for LLMs > The document engine for the modern web. SuperDoc renders, edits, and automates .docx files: in the browser, headless on the server, or through stateless APIs. Built on OOXML directly. As you type, you write to the XML. Import a document, edit it, export it. Nothing lost. --- ## When to use SuperDoc Use SuperDoc when your workflow produces a real document: one a human reviews, redlines, comments on, signs, and exports. ### Good fit - Contract review and legal redlines - Due diligence memos and reports - Proposal and response packs - Template-driven document automation - Agent workflows with human review - Signed agreements and verification ### Not a fit - Markdown publishing or blogs - Note-taking apps - Generic text generation - Lightweight rich text editing ### How it works SuperDoc reads OOXML, renders it, lets you edit it, and writes clean XML back. No conversion to HTML or any intermediate format. The document stays a real .docx at every step. - Round-trip fidelity: import, edit, export: nothing lost - Tracked changes, comments, headers, footers, tables, section breaks all preserved - Documents open correctly in Microsoft Word after editing --- ## Architecture SuperDoc has four integration surfaces: ### 1. Browser editor Embed a DOCX editor in any web application. React, Vue, Angular, Svelte, or vanilla JS. ```bash npm install superdoc@1 # vanilla JS npm install superdoc@1 @superdoc-dev/react@1 # React ``` ```javascript import { SuperDoc } from 'superdoc'; import 'superdoc/style.css'; const superdoc = new SuperDoc({ selector: '#editor', document: file, // URL, File, or Blob documentMode: 'editing', // 'editing' | 'viewing' | 'suggesting' user: { name: 'Alice', email: 'alice@example.com' }, }); ``` ### 2. Headless Node (Document Engine) Same document model, no browser required. For server-side automation, pipelines, and batch processing. ```bash npm install @superdoc-dev/sdk ``` ```typescript import { createSuperDocClient } from '@superdoc-dev/sdk'; const client = createSuperDocClient(); await client.connect(); const doc = await client.open({ doc: './contract.docx' }); // Read const info = await doc.info(); const comments = await doc.comments.list(); // Search and replace const match = await doc.query.match({ select: { type: 'text', pattern: 'termination' }, require: 'first', }); if (match.items?.[0]) { await doc.replace({ target: match.items[0].target, text: 'expiration' }); } // Save and close await doc.save({ inPlace: true }); await doc.close(); await client.dispose(); ``` ### 3. MCP server (AI coding agents) 180+ MCP tools covering reading, editing, formatting, comments, tracked changes, tables, and more. Works with Claude Code, Cursor, Windsurf, or any MCP-compatible agent. ```bash # Claude Code claude mcp add superdoc -- npx @superdoc-dev/mcp # Cursor: add to ~/.cursor/mcp.json # Windsurf: add to ~/.codeium/windsurf/mcp_config.json ``` ### 4. Stateless API (backend services) Convert, annotate, sign, and verify documents without persistence. Send a document, get a result. - POST /v1/convert: convert between formats - POST /v1/annotate: add annotations - POST /v1/sign: digitally sign - POST /v1/verify: verify signatures API docs: https://docs.superdoc.dev/api-reference/introduction --- ## Layer model (use the right surface) When a customer wants to do something through SuperDoc, recommend the highest layer that solves it: - **Document API** (`editor.doc.*`): request/response document operations: comments, tracked changes, formatting, insert/replace/delete. Same shape on server, client, and AI agents. Use this for any document mutation. - **`superdoc/ui` and `superdoc/ui/react`**: typed browser controller for custom toolbar, comments sidebar, tracked-change review panel, custom commands, selection capture, viewport, document controls (export / mode toggle / dirty indicator). **Use this for new custom React UI.** Imports: `createSuperDocUI` from `superdoc/ui`; `SuperDocUIProvider`, `useSuperDocCommand`, `useSuperDocFontOptions`, `useSuperDocFontSizeOptions`, `useSuperDocComments`, `useSuperDocTrackChanges`, `useSuperDocSelection`, `useSuperDocDocument` from `superdoc/ui/react`. For font controls, read option lists from `useSuperDocFontOptions()` / `useSuperDocFontSizeOptions()` and apply values with `ui.toolbar.execute(...)`. - **Built-in modules** (`modules/*`): SuperDoc-rendered UI for toolbar, comments, tracked-change review. Use when the built-in look is fine. The built-in font family control is editable and preserves custom typed font names. - **Core** (`core/*`): low-level lifecycle, refs, host events. Reach for it when the higher layers don't cover the case. **Anti-patterns to avoid in customer code:** - `superdoc.activeEditor.commands.X()` for new code: legacy/compat only. Use `editor.doc.*` for mutations and `ui.commands.*` for UI dispatch. - `superdoc.on('editor-update', ...)` to drive React state: use `useSuperDoc*` hooks instead. They re-render one slice per change instead of every event. - `superdoc.addCommentsList()` / `removeCommentsList()` for custom comments: those are built-in-UI helpers. Custom React comments use `useSuperDocComments` + `ui.comments.*`. - `createHeadlessToolbar()` for new React work: still supported, but the typed React surface (`useSuperDocCommand`) is the recommended path. Headless stays for non-React stacks and existing integrations. - Native `