Superdoc

Create, edit, and manipulate DOCX files using SuperDoc - a modern document editor with custom rendering pipeline. Use when you need to programmatically work...

Security Scan

The skill's requirements and instructions are consistent with a DOCX manipulation library: it documents use of an npm package, shows file read/write examples, and requests no credentials or system-level privileges.

Purpose & Capability

Name/description (DOCX creation/editing) align with the content: examples, headless/browser notes, and React integration all relate to programmatic DOCX manipulation. There are no unrelated required env vars, binaries, or config paths.

Instruction Scope

SKILL.md instructs the agent to read and write local files (input.docx, template.docx, clients.json, output/). This is expected for a document-editing skill, but users should be aware this skill's examples perform arbitrary filesystem I/O on local documents and templates.

Install Mechanism

This is an instruction-only skill (no install spec). The docs recommend running `npm install` (and global install examples). Because the skill doesn't install anything automatically, the install risk is low; however, following its guidance will pull packages (superdoc, jsdom, @superdoc-dev/react) from npm, so users should vet those packages and prefer local installs over global ones.

Credentials

The skill declares no environment variables, no credentials, and no config paths. The examples do not reference secrets or unrelated env vars.

Persistence & Privilege

always is false and the skill does not request persistent/automatic inclusion or system config changes. It does not request elevated privileges or modify other skills.

Assessment

This skill appears to be what it says: documentation for using an npm-based DOCX library. Before installing or running code from it: verify the npm package/vendor (confirm the GitHub repo and package integrity), prefer local project installs instead of global installs, inspect package contents or source for unexpected network calls, and be cautious when processing untrusted DOCX files (they can contain external links or embedded content). Also note the library is AGPLv3 by the reference—check licensing implications for your project. If you need extra assurance, fetch the package from the npm registry and review its package.json and published files before running any scripts that read/write your documents.

SuperDoc Skill

SuperDoc is a modern DOCX editor providing programmatic document manipulation with full formatting control.

Installed: v1.17.0 at /usr/local/lib/node_modules/superdoc

Quick Start

Create a new document

const { Document, Paragraph, TextRun } = require('superdoc');

const doc = new Document({
  sections: [{
    children: [
      new Paragraph({
        children: [
          new TextRun({ text: "Hello World", bold: true })
        ]
      })
    ]
  }]
});

// Save to file
const fs = require('fs');
const Packer = require('superdoc').Packer;
Packer.toBuffer(doc).then(buffer => {
  fs.writeFileSync('output.docx', buffer);
});

Edit an existing document

const { Document } = require('superdoc');
const fs = require('fs');

// Load existing DOCX
const buffer = fs.readFileSync('input.docx');
const doc = await Document.load(buffer);

// Find and replace text
doc.sections[0].children.forEach(para => {
  para.children.forEach(run => {
    if (run.text) {
      run.text = run.text.replace(/Company A/g, 'Company B');
    }
  });
});

// Save modified document
const output = await Packer.toBuffer(doc);
fs.writeFileSync('output.docx', output);

Template generation (batch)

const { Document, Paragraph, TextRun } = require('superdoc');
const fs = require('fs');

// Load template
const template = fs.readFileSync('template.docx');

// Generate personalized documents
const clients = require('./clients.json');
for (const client of clients) {
  const doc = await Document.load(template);
  
  // Replace placeholders
  doc.sections[0].children.forEach(para => {
    para.children.forEach(run => {
      if (run.text) {
        run.text = run.text
          .replace('{{NAME}}', client.name)
          .replace('{{EMAIL}}', client.email);
      }
    });
  });
  
  const output = await Packer.toBuffer(doc);
  fs.writeFileSync(`output/${client.id}.docx`, output);
}

Common Workflows

Document creation flow

1. Import required classes: Document, Paragraph, TextRun, Packer
2. Build document structure with sections and paragraphs
3. Apply formatting (bold, italic, fonts, colors)
4. Export using Packer.toBuffer() or Packer.toBlob()

Document editing flow

1. Load existing DOCX: Document.load(buffer)
2. Navigate structure: doc.sections[i].children (paragraphs)
3. Modify content: update run.text or formatting properties
4. Save: Packer.toBuffer(doc)

Error handling

Common issues:

• File not found: Check path before fs.readFileSync()
• Invalid DOCX: Wrap Document.load() in try-catch
• Memory limits: For large batches, process in chunks (max 100 docs at once)

Headless Node.js Usage

SuperDoc requires browser APIs by default. In CLI/headless contexts:

Setup (one-time):

npm install --global superdoc jsdom

Polyfill browser APIs:

const { JSDOM } = require('jsdom');
const dom = new JSDOM('<!DOCTYPE html>');
global.window = dom.window;
global.document = window.document;
global.localStorage = {
  getItem: () => null,
  setItem: () => {},
  removeItem: () => {}
};

// Now import SuperDoc
const { Document } = require('superdoc');

Alternative: Use browser tool For complex rendering or UI-dependent features, use OpenClaw's browser tool to run SuperDoc in a real browser context.

React Integration

Install:

npm install @superdoc-dev/react

Basic usage:

import { SuperDocEditor } from '@superdoc-dev/react';
import { useState } from 'react';

function App() {
  const [doc, setDoc] = useState(null);
  
  return (
    <SuperDocEditor
      document={doc}
      onChange={setDoc}
      onSave={(buffer) => {
        // Handle save
        const blob = new Blob([buffer], { 
          type: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document' 
        });
        // Download or upload blob
      }}
    />
  );
}

Key props:

• document: Document instance or null
• onChange: Callback when document changes
• onSave: Callback with buffer when user saves
• toolbar: Custom toolbar config (optional)

When NOT to Use SuperDoc

• PDF editing: Use pdf-lib or similar
• Document analysis/summarization: Use text extraction + LLM
• OCR: Use tesseract or cloud OCR services
• Simple text extraction: Use mammoth.js (lighter weight)
• Legacy .doc (not .docx): Use LibreOffice or online converters

Advanced Usage

For detailed API reference, advanced formatting, tracked changes, and custom rendering:

• See references/superdoc-reference.md
• Repository: https://github.com/superdoc-dev/superdoc

Troubleshooting

"localStorage is not defined" → Add localStorage polyfill (see Headless Usage section)

"Cannot read property 'children' of undefined" → Document structure may be empty; check doc.sections.length > 0

Large files slow/crash → Process in batches; consider streaming for files >10MB

Formatting not preserved → Ensure you're modifying properties, not replacing objects