Quick start

@quirekit/lit-docx does two things: parseDocx reads a DOCX file into LitAST, a document tree made of plain JSON objects, and generateDocx writes LitAST back to DOCX. It does not depend on any editor and never touches the file system; it only works with bytes, so the same code runs in browsers and Node. It is a QuireKit commercial component distributed as a compiled build: development and evaluation are free, the free edition runs in production with an evaluation notice, and a license key removes the notice. Individuals, education, open-source projects and small teams can request a free community key.

Installation

lit-docx is a preview and has not been published to npm yet. Once published, install it with:

pnpm add @quirekit/lit-docx

It requires Node 18 or later, or a modern browser. The package ships both ESM and CommonJS builds.

Try it in the browser

The example below runs entirely in this page. It loads a sample report generated by lit-docx; switch to “Your file” to open your own .docx. Inspect the result as a rendered preview or as LitAST, then generate a new .docx from the LitAST.

Read a DOCX

parseDocx takes the bytes of a complete file (Uint8Array) and returns the document tree ast together with non-fatal warnings. A file that is not DOCX throws DocxPackageError.

Start with two steps: obtain bytes, then parse them. Here file is a browser File selected by the user:

import { parseDocx } from '@quirekit/lit-docx'
const bytes = new Uint8Array(await file.arrayBuffer())
const { ast, warnings } = await parseDocx(bytes)

ast is the tree to read or modify; warnings describes parsing issues to explain to the user. In Node, obtain bytes with readFile() and use the same parser.

For text extraction, inspect recipes/read-text.ts for reading and parsing, and shared/text.ts for tree traversal.

import { readFile } from "node:fs/promises";
import { DocxPackageError, parseDocx } from "@quirekit/lit-docx";
import { collectParagraphText } from "../shared/text";

/**
 * Reads a DOCX file and prints its paragraphs and parser warnings.
 * @param path - DOCX file on disk.
 * @returns Resolves after printing.
 */
export async function printDocx(path: string): Promise<void> {
  try {
    const { ast, warnings } = await parseDocx(new Uint8Array(await readFile(path)));
    for (const line of collectParagraphText(ast)) console.log(line);
    for (const warning of warnings) console.warn(`[${warning.code}] ${warning.message}`);
  } catch (error) {
    // Not a DOCX ZIP package at all, or an encrypted / legacy .doc container.
    if (error instanceof DocxPackageError) console.error(`Cannot open ${path}: ${error.code}`);
    else throw error;
  }
}

The collectParagraphText helper used above just walks the tree: the words of paragraphs and headings live in their text children.

Generate a DOCX

LitAST is plain objects. You can write it by hand or with the package's docx authoring helpers; both produce exactly the same structure. The report in the example above is built this way: a title, formatted text, a bullet list, a bordered table with a shaded header row, a link, and an A4 page with a header and footer. shared/report.ts builds that report; recipes/create-report.ts generates bytes and writes them. First, generate just one paragraph:

import { generateDocx } from '@quirekit/lit-docx'
const bytes = await generateDocx({
  type: 'document',
  children: [{ type: 'paragraph', children: [{ type: 'text', text: 'Hello' }] }],
})

Write bytes to a Node file or download them in a browser. Inspect the complete report by file below:

import { writeFile } from "node:fs/promises";
import { generateDocx } from "@quirekit/lit-docx";
import { createReport } from "../shared/report";

/**
 * Writes the report to disk.
 * @param path - Destination `.docx` path.
 * @returns Resolves once the file is written.
 */
export async function writeReport(path: string): Promise<void> {
  await writeFile(path, await generateDocx(createReport()));
}

Next steps

• Reading DOCX: input types, parse options, warnings and errors.
• Generating DOCX: hand-written nodes, the docx helpers, and unit conventions.
• The LitAST node model: which nodes and marks exist and what they look like.
• Round trips and preservation: what survives reading a file and writing it back, and what does not.
• Support matrix: how each Word feature is supported for reading and for generating.