docx-templer

A high-performance Node.js library for merging and embedding DOCX documents using simple placeholders. Designed to be fast, reliable, and safe against common Word XML pitfalls.

✨ Features

• Merge one DOCX into another using clean placeholders
• Embed multiple documents into a single template
• Works reliably with Word-generated XML (handles split runs)
• Buffer-based API (perfect for APIs, servers, and cloud environments)
• No Word automation or OS-level dependencies

📦 Installation

npm install docx-templer

For TypeScript projects:

npm install --save-dev @types/docx-templer

🚀 Usage

Merger (Recommended)

Merges a single source DOCX into a base template. This is the most portable method and works across platforms such as Microsoft Word, Google Docs, and online viewers.

const { Merger } = require('docx-templer');
const fs = require('fs');

const templateBuffer = fs.readFileSync('template.docx');
const sourceBuffer = fs.readFileSync('source.docx');

Merger(templateBuffer, sourceBuffer, 'MY_PLACEHOLDER')
  .then(mergedBuffer => {
    fs.writeFileSync('output.docx', mergedBuffer);
  });

Embedder

Embeds multiple DOCX documents into a single template using multiple placeholders.

⚠️ Note: This method relies on Word-specific embedding behavior. It works best in Microsoft Word and may not be supported by platforms like Google Docs.

const { Embedder } = require('docx-templer');
const fs = require('fs');

const templateBuffer = fs.readFileSync('template.docx');
const sourceBuffers = [
  { buffer: fs.readFileSync('source1.docx'), placeholder: 'key1' },
  { buffer: fs.readFileSync('source2.docx'), placeholder: 'key2' }
];

Embedder(templateBuffer, sourceBuffers)
  .then(embeddedBuffer => {
    fs.writeFileSync('output.docx', embeddedBuffer);
  });

📝 How to Place Tags in Word

To ensure successful merging, follow these rules when preparing your template.docx:

1. Tag Pattern

Always use three underscores before and after your key.

Correct:

___YOURPLACEHOLDER___

Incorrect:

{YOURPLACEHOLDER}
YOURPLACEHOLDER

2. Best Practices

• Type tags cleanly
  Avoid backspacing while typing the tag. If you make a mistake, delete the whole line and re-type it.
  This prevents Word from creating extra XML nodes.

• Stand-alone paragraphs
  For the best layout, place the tag on its own line.
  The library replaces the entire paragraph containing the tag with the content of the source document.

📚 API Reference

Merger(templateBuffer, sourceBuffer, placeholder)

Merges a single source document into the template at the specified placeholder.

• templateBuffer: Buffer
  The main template document.

• sourceBuffer: Buffer
  The document to be inserted.

• placeholder: string
  The key inside the underscores (e.g., passing 'DATA' looks for ___DATA___).

• Returns: Promise<Buffer>

Embedder(templateBuffer, sourceBuffers)

Embeds multiple source documents into the template using multiple placeholders.

• templateBuffer: Buffer
  The main template document.

• sourceBuffers: Array<{ buffer: Buffer, placeholder: string }>
  An array of objects containing the source document buffer and its unique placeholder key.

• Returns: Promise<Buffer>

✅ Recommendations

• Use Merger wherever possible for maximum compatibility
• Keep placeholders isolated in their own paragraph
• Avoid styling or editing placeholders after typing them
• Maintain basic formatting and standard fonts in templates and source documents
• Avoid nested formatting, complex styles, deeply nested tables, or excessive section breaks when using Merger
• If the Merger output shows a warning while opening the document in Word, try using Embedder instead for a better viewing and editing experience
• For complex documents (heavy formatting, multiple tables, headers/footers, or mixed content), prefer the Embedder method as it is more resilient and helps avoid Word XML corruption or broken-document errors

📄 License

MIT