HTML to real Word docs, not layout theater

Exporting HTML as a Word document is a problem every report-heavy app eventually hits. The usual exits are ugly: print-to-PDF and hope nobody needs to edit, ship a blob of HTML that Word opens as a degraded mess, call a cloud converter, or hand-build OOXML with something like docx. What teams actually want is simpler: take the HTML they already render for the web, and get a .docx people can open, rewrite, and share without fighting the layout.

DOM-docx is a small MIT library that aims at that middle path. It converts semantic HTML fragments into native OOXML (paragraphs, runs, lists, tables, images) rather than screenshots or layout hacks. It is early (v0.1.x), opinionated about what it supports, and interesting less for novelty than for how deliberately it scopes the problem.

The gap it is filling

Client-side DOCX generation is not new. Older pure-JS tools could write basic runs and formatting; commercial APIs and online converters turn pages into Word files at scale. The recurring failure mode is the same: either the output is not really editable Word structure, or styles and structure drift as soon as the HTML leaves a browser.

DOM-docx’s pitch is structural fidelity. The default path walks a body fragment (no full document shell required) and maps it to real Word constructs. Headings, paragraphs, lists (including list-style-type), tables, links, inline formatting, blockquotes, simple flex rows, and images are first-class. Page size, margins, headers/footers, page numbers, and a table of contents are configurable. That is the right target for invoices, quarterly reports, CMS “export to Word,” and internal docs where the recipient will edit in Word or LibreOffice, not just view a PDF.

The library also ships a visual regression loop for its own development: HTML rendered in Chromium, converted to DOCX, rasterized through LibreOffice, then scored for layout and structural fidelity. LibreOffice is a test dependency only, not a runtime requirement. That is a healthier stance than “it looked fine once in Word on my machine.”

Two style paths, one light default

Install is intentionally thin:

npm install dom-docx

Node 20+, default path pure JS. Runtime deps are docx, cheerio, and fflate. Playwright is an optional peer, loaded only when you ask for computed styles or in-place rasterization.

Inline (default). Styles come from attributes on the fragment. No browser, no Playwright. This is what you get from npm install alone, and it is the supported path for most server-side report generation.

Computed. Resolves <style> blocks and class/id selectors via getComputedStyle. On Node that means Playwright + Chromium; in the browser bundle it uses the live tab. Useful when your HTML is stylesheet-driven or you already have a rendered SPA fragment (root / rootSelector).

Rasterize in place. Optional path for <canvas> and complex SVG (for example chart libraries). It turns those into PNG images before conversion; scale: 2 supersamples for sharper Word images. Simple inline SVG (rects + text) can still go native without rasterization.

Browser usage is a separate entry:

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

const blob = await convertHtmlToDocx(html);
// download via object URL, or post the bytes to your API

Node is the same idea with a Buffer/Uint8Array write. There is also a CLI (npx dom-docx input.html -o out.docx, stdin/stdout pipelines) for glue scripts without writing code.

What this means in a real workflow

If you already build report UIs in HTML, the adoption path is: emit a clean body fragment (inline styles or a controlled stylesheet), call convertHtmlToDocx, stream the bytes to S3 or the browser. That replaces a lot of ad hoc “build the document with the OOXML library by hand” code, and it is cleaner than shipping HTML that Word half-understands.

Trade-offs to plan for:

• Inline is the production default. External stylesheets on the inline path are not supported. Either inline critical styles, or pay the Playwright cost for computed mode.
• Layout model is limited. v0.1.x does not do CSS grid, float layout, web fonts, or forms. Simple flex rows up to four items work; complex page chrome will not. Treat this as semantic content export, not pixel-perfect web capture.
• Charts are images (when complex). Native editable chart objects are not the goal. Rasterization is honest about that; dial scale if the Word file looks soft.
• Images need a resolver for remotes. data: URLs work; remote assets go through your imageResolver so you control fetch, auth, and caching.
• Defaults are boring on purpose. US Letter, 1″ margins, Arial 10.5pt. Override page, font, metadata, and headers if your brand pack matters.

Compared with pure docx authoring, you trade fine-grained OOXML control for “HTML is the source of truth.” Compared with cloud HTML→DOCX APIs, you keep data on your box and avoid per-page pricing, at the cost of supporting only what the library maps. Compared with print/PDF pipelines, you get an editable document at the cost of weaker layout guarantees.

Production-ready or not yet

Call it promising infrastructure, not a finished product. The capability matrix is explicit: solid for headings, lists, tables, links, basic formatting, and controlled images; advanced only when you opt into Playwright or rasterization; unsupported for grid-heavy and form-heavy HTML. Stars and forks are still low; the public surface is young.

Worth your attention now if:

• you generate structured reports from HTML you control,
• recipients must edit in Word,
• you can keep fragments in the supported subset (or invest in inline styles / a thin adapter layer).

Wait (or prototype only) if your templates depend on modern CSS layout, custom web fonts, or pixel-matched design systems. In those cases PDF or a full server Word engine still wins.

The useful idea underneath the package is the contract: HTML as a semantic input, OOXML as a native output, with optional browser assist only when styles or charts demand it. That is a better default than another converter that pretends the web and Word share a layout engine. If the supported surface keeps expanding under that same discipline, DOM-docx becomes an easy dependency for “export as Word” rather than a research project. For v0.1, treat it as a sharp tool for constrained HTML, not a general web-to-Office panacea.