📄 docx-merge

A fast and lightweight Node.js library written in TypeScript for merging two Microsoft Word (.docx) documents into one. Easily insert content at specific positions or based on placeholder patterns.

📦 Installation

Install via npm:

npm install @benedicte/docx-merge

📚 Dependencies

Only two lightweight dependencies:

• adm-zip – for extracting and rebuilding .docx (ZIP) files
• fast-xml-parser – for parsing and modifying the DOCX XML content

🛠️ API

mergeDocx(
  sourcePathOrBuffer: string | Buffer,
  contentPathOrBuffer: string | Buffer,
  options: {
    outputPath?: string;
    pattern?: string;
    insertStart?: boolean;
    insertEnd?: boolean;
  }
): void | buffer

Parameters:

• sourcePathOrBuffer (required) – Path to the base .docx file or the Buffer
• contentPathOrBuffer (required) – Path to the .docx file to insert into the base or the Buffer
• options:
  • outputPath – If provided, writes the merged document to this path. If omitted, returns a Buffer
  • pattern – String pattern in the source file to replace with the inserted content
  • insertStart – Insert the content at the beginning of the source file
  • insertEnd – Insert the content at the end of the source file

🔔 Note: You can combine pattern, insertStart, and insertEnd and at least one is required.

💡 Examples

Replace a placeholder in the source DOCX

import { mergeDocx } from "@benedicte/docx-merge";

mergeDocx("./source.docx", "./table.docx", {
  outputPath: "./output.docx",
  pattern: "{{table}}",
});

Get the merged result as a Buffer

import { mergeDocx } from "@benedicte/docx-merge";

const buffer = mergeDocx("./source.docx", "./table.docx", {
  pattern: "{{table}}",
});

// Use buffer (e.g., send as a response in a server)

Input files as Buffers

import { mergeDocx } from "@benedicte/docx-merge";

const sourceBuffer = readFileSync('./source_file.docx');
const contentBuffer = readFileSync('./content_to_insert_in_source_file.docx');

const buffer = mergeDocx(sourceBuffer, contentBuffer, {
  outputPath: "./output.docx",
  pattern: "{{table}}",
});

Insert at the start of the document

import { mergeDocx } from "@benedicte/docx-merge";

mergeDocx("./source.docx", "./table.docx", {
  outputPath: "./output.docx",
  insertStart: true,
});

Insert at the end of the document

import { mergeDocx } from "@benedicte/docx-merge";

mergeDocx("./source.docx", "./table.docx", {
  outputPath: "./output.docx",
  insertEnd: true,
});

🧪 Testing

This project uses Vitest for unit testing.

To run tests:

npm run test

🔒 License

MIT

🤝 Contributing

Contributions, bug reports, and feature requests are welcome! Feel free to open an issue or submit a pull request.