dom-docx: Transforming HTML into Editable Word Documents

dom-docx is an MIT-licensed library designed to convert semantic HTML fragments into native, fully editable Microsoft Word documents (OOXML). It handles essential elements such as paragraphs, runs, tables, lists, and images.

🛠 The Development Philosophy

The library was developed using a rigorous visual regression loop to ensure high fidelity:

---

🚀 Execution Modes & Requirements

Depending on your needs, you can choose between different style sources. Note that the default "inline" path requires no browser environment.

Note: On Node.js, playwright is an optional peer dependency. It is only loaded lazily when styleSource: "computed" or rasterizeInPlace is utilized.

Installation

To get started, run: npm install dom-docx

This installs only docx, cheerio, and fflate. If you require the advanced computed or rasterization paths, you must manually install the browser dependencies:

npm install playwright
npx playwright install chromium

---

💻 Usage Guide

Command Line Interface (CLI)

You can convert files directly from your terminal without writing code:

• Basic conversion: npx dom-docx input.html -o output.docx
• Default output: npx dom-docx input.html (creates input.docx)
• Pipeline mode: cat fragment.html | npx dom-docx - -o - (stdin $\rightarrow$ binary stdout)
• Computed styles: npx dom-docx input.html -s computed (requires Playwright)
• Global install: npm install -g dom-docx $\rightarrow$ then simply run dom-docx

Browser Integration

import { convertHtmlToDocx } from "dom-docx/browser";

const html = `
  <h1 style="color:#1a1a2e">Quarterly Report</h1>
  <p>Revenue grew <strong>12%</strong> year over year.</p>
  <ul>
    <li>North America</li>
    <li>EMEA</li>
  </ul>
`;

const blob = await convertHtmlToDocx(html);

Node.js Integration

import { writeFile } from "node:fs/promises";
import { convertHtmlToDocx } from "dom-docx";

const html = `
  <h1 style="color:#1a1a2e">Quarterly Report</h1>
  <p>Revenue grew <strong>12%</strong> year over year.</p>
  <ul>
    <li>North America</li>
    <li>EMEA</li>
  </ul>
`;

const docx = await convertHtmlToDocx(html);
await writeFile("output.docx", docx);

Important: Provide only the body fragment; do not include <html> or <body> tags.

---

📊 Feature Matrix (v0.1.x)

✅ Supported Features

• Basic Formatting: Headings, paragraphs, links, and inline styles.
• Lists: <ul> and <ol> (including list-style-type).
• Tables: Standard table structures.
• Layout: Block backgrounds, blockquotes, and <hr>.
• Flexbox: Simple flex rows where items $\le 4$.
• Images: Remote URLs and data: URIs (via imageResolver).
• Document Settings: Page margins, orientation, size, default fonts, and metadata.
• Advanced Docs: Header/Footer HTML, page numbering, and Table of Contents.
• SVG/CSS: Low-complexity inline SVGs (text + bars) and CSS-based bar divs in tables (converted to native shaded bands).

🌟 Advanced Capabilities

• Computed Styles: Resolves #id and .class selectors using getComputedStyle.
  • Node: Launches headless Chromium.
  • Browser: Uses the active tab's DOM.
• Rasterization: Converts complex SVGs (e.g., Highcharts) or Canvas elements into PNGs.
  • Tip: Use rasterizeInPlace: { scale: 2 } for high-density, sharper images.

❌ Not Supported / Limitations

• External stylesheets (when using the inline path).
• Web fonts and CSS Grid/Float layouts.
• HTML Forms, <pre>, <dl>, or table rowspan.
• Complex SVG paths/gradients (unless rasterizeInPlace is used).
• First-page/Even-page variants for headers and footers.

---

🛠 API Reference

convertHtmlToDocx(html, options?)

Returns a Promise<Buffer> (in Node.js) containing the valid .docx binary.

import { convertHtmlToDocx, type ConvertOptions } from "dom-docx";

const docx = await convertHtmlToDocx(html, {
  // options here
});

For more detailed information, refer to API.md for full options and AGENTS.md for HTML authoring tiers.