docxml

5.15.1 verified Fri May 01 auth: no javascript

docxml is a TypeScript library for building and parsing .docx files (OXML format) from scratch or from templates. The current stable version is 5.15.1, released actively with several updates per year. Key differentiators include support for both Node.js and Deno, JSX syntax for declarative document composition, template rendering with parameterized DOTX files, and coverage of features like tables, images, headers/footers, change tracking, comments, and reference fields. It provides a fully typed API and supports both programmatic and XML-driven document creation.

Common errors

error Error: self-referencing import map not allowed ↓

cause Using a Deno import map that references the package itself incorrectly.

fix

Use the correct import map URL (e.g., from deno.land/x/docxml) or an npm specifier if using Node.

error TypeError: Docx.fromJsx is not a function ↓

cause Using CommonJS `require('docxml')` without destructuring the default export.

fix

Use const { default: Docx } = require('docxml') or switch to ESM imports.

error ReferenceError: React is not defined ↓

cause Using JSX without the correct JSX pragma (e.g., `/** @jsx Docx.jsx */`).

fix

Add /** @jsx Docx.jsx */ at the top of the JSX file, or configure your transpiler to use Docx.jsx.

error Error: DOCX file not saved: ENOENT: no such file or directory, open '...' ↓

cause Output directory does not exist.

fix

Create the directory before calling toFile(), or use toBuffer() and write manually after ensuring the path exists.

Warnings

breaking In v5.0.0, the API changed from object-based to async component-based. Old `docx` create function removed. ↓

fix Use `Docx.fromJsx()` or `Docx.fromNothing()` to create documents.

deprecated The `Document` class is deprecated in favor of `Docx` namespace. ↓

fix Replace `new Document()` with `Docx.fromJsx()` or `Docx.fromNothing()`.

gotcha JSX requires a transpiler (e.g., Babel or TypeScript) and the `/** @jsx Docx.jsx */` pragma or equivalent configuration. ↓

fix Add `/** @jsx Docx.jsx */` at the top of JSX files, or configure your transpiler to use `Docx.jsx` as the JSX factory.

gotcha In Node.js CommonJS, the default import must be destructured as `const { default: Docx } = require('docxml')` because the package exports ESM first. ↓

fix Use `const { default: Docx } = require('docxml')` or switch to ESM imports.

gotcha Saving a file with `toFile()` may fail if the output directory doesn't exist. The library does not create directories automatically. ↓

fix Ensure the output directory exists before calling `toFile()`, or use `toBuffer()` and write the buffer yourself.

Install

npm install docxml

yarn add docxml

pnpm add docxml

Imports

Docx
wrong
```
const Docx = require('docxml')
```
correct
```
import Docx from 'docxml'
```
Default export; in Node.js CJS requires destructuring: const { default: Docx } = require('docxml')

Paragraph

wrong

const Paragraph = require('docxml/Paragraph')

correct

import { Paragraph } from 'docxml'

Named export; available from the main package

Text
```
import { Text } from 'docxml'
```
Named export for text content
Docx
wrong
```
import Docx from 'docxml/src/index.ts'
```
correct
```
import { default as Docx } from 'docxml'
```
For Deno, import from 'https://deno.land/x/docxml/mod.ts' or via import map

Quickstart

Creates a simple DOCX file with a centered paragraph and saves it to disk.

import Docx, { Paragraph, Text } from 'docxml';

async function main() {
  const doc = await Docx.fromJsx(
    <Paragraph alignment="center">
      <Text>Hello World</Text>
    </Paragraph>
  );
  await doc.toFile('hello.docx');
}

main().catch(console.error);