dom-docx: HTML to Native Editable Word Documents

dom-docx: HTML to Native Editable Word Documents

Overview

dom-docx is a TypeScript library designed to convert semantic HTML fragments into native, editable Word documents (OOXML). Unlike tools that produce screenshots or layout hacks, dom-docx generates real Word structures—paragraphs, runs, lists, and tables—ensuring the resulting documents are fully editable in Microsoft Word and LibreOffice.

Core Capabilities

Supported HTML Elements

In its default inline mode, the library supports a wide range of semantic HTML:

  • Text & Structure: Headings, paragraphs, lists (<ul>, <ol>), and blockquotes.
  • Formatting: Inline formatting (<strong>, <em>), links, and horizontal rules (<hr>).
  • Citations & Layout: Data tables, shaded callouts, and simple flex rows (up to 4 items).
  • Visuals: data: images and low-complexity inline SVG (specifically bars and text).

Advanced Rendering Options

Depending on the same requirements for style and complexity, dom-docx offers three distinct paths for conversion:

  1. Inline Style Resolution (styleSource: "inline"): The default, pure JavaScript path. It parses style="" attributes directly and requires no browser environment.
  2. Computed Style Resolution (styleSource: "computed"): Resolves <style> blocks, classes, and ID selectors using getComputedStyle.
    • In Node.js: Requires Playwright and Chromium to render the fragment headless.
    • In the Browser: Uses the live DOM of the user's tab, requiring no additional installations.
  3. Rasterization (rasterizeInPlace): Converts <canvas> and complex <svg> (such as Highcharts) into PNG images before conversion. This is recommended for complex charts, with a suggested scale: 2 for high-density output.

Technical Architecture

The Conversion Pipeline

The library maps HTML to OOXML through a three-stage process:

  1. Style Resolution: Determining the final styles via inline attributes or browser computed styles.
  2. Visitor Pattern: A Cheerio walk that transforms HTML elements into docx paragraphs, tables, numbering, and hyperlinks.
  3. Pack & Patch: Generating the OOXML and applying patches to ensure list numbering and shaded-block alignment are consistent across Word and LibreOffice PDF exports.

Quality Assurance via Visual Regression

The author developed dom-docx using an "Autoresearch" pattern—an autonomous loop that iteratively improves fidelity. The process involves:

  • Rendering HTML in Chromium.
  • Converting the HTML to .docx via dom-docx.
  • Rasterizing the .docx file using LibreOffice.
  • Comparing the browser screenshot against the LibreOffice screenshot to score layout fidelity, editability, and speed.

This loop was run against 37 real-world HTML patterns to ensure high concordance with human quality ratings.

Integration and Usage

Installation

npm install dom-docx

Note: Node.js ≥ 20 is required. Playwright is an optional peer dependency used only for computed styles or rasterization in Node.

Quick Start Examples

Browser Usage (Pure JS, no Playwright):

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>`;
const blob = await convertHtmlToDocx(html);
const a = document.createElement("a");
a.href = URL.createObjectURL(blob);
a.download = "output.docx";
a.click();

Node.js Usage:

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`;
const docx = await convertHtmlToDocx(html);
await writeFile("output.docx", docx);

CLI Tool

For quick conversions without code, the library provides a CLI:

npx dom-docx input.html -o output.docx

Limitations

In version 0.1.x, the following features are not supported:

  • External stylesheets on the inline path.
  • Web fonts, CSS grid, float layouts, and absolute positioning.
  • Forms, <dl>, and table rowspan.
  • Complex SVG paths and gradients (unless rasterizeInPlace is used).
  • Guaranteed multi-page layout fidelity or specific header/footer variants for first/even pages.

Sources