Patching

Patch an existing .docx template in three ways: replace {{placeholder}} tokens, find-and-replace literal text, or override document metadata. Patch content can be inline runs, block-level elements (paragraphs, tables), images, and hyperlinks.

#patchDocument

Replaces placeholders in an existing .docx file:

import { patchDocument } from "@office-open/docx";
import { readFileSync, writeFileSync } from "node:fs";

const result = await patchDocument({
  outputType: "nodebuffer",
  data: readFileSync("template.docx"),
  placeholders: {
    name: {
      type: "paragraph",
      children: [{ text: "John Doe" }],
    },
  },
});

writeFileSync("output.docx", result);

#Patch types

Each patch is discriminated by a bare type string literal:

#"paragraph"

Replaces the placeholder text inside a paragraph with new runs. The original run's formatting properties (font, size, color, bold, etc.) are preserved by default.

{
  "placeholders": {
    "title": {
      "type": "paragraph",
      "children": [
        {
          "text": "Hello ",
          "bold": true
        },
        {
          "text": "World"
        }
      ]
    }
  }
}

#"document"

Replaces the placeholder with block-level elements (paragraphs, tables, etc.). The surrounding context is preserved.

placeholders: {
  content: {
    type: "document",
    children: [
      { paragraph: { children: ["First paragraph"] } },
      { paragraph: { children: ["Second paragraph"] } },
      {
        table: {
          rows: [
            {
              cells: [
                { children: [{ paragraph: { children: ["Cell"] } }] },
              ],
            },
          ],
        },
      },
    ],
  },
}

#Images

Replace a placeholder with an image:

placeholders: {
  logo: {
    type: "paragraph",
    children: [
      {
        picture: {
          type: "png",
          data: readFileSync("logo.png"),
          transformation: { width: "5.3cm", height: "2.6cm" },
        },
      },
    ],
  },
}

#Hyperlinks

Include hyperlinks in patch content:

{
  "placeholders": {
    "website": {
      "type": "paragraph",
      "children": [
        {
          "text": "Visit "
        },
        {
          "hyperlink": {
            "children": [
              {
                "text": "our website"
              }
            ],
            "url": "https://example.com"
          }
        }
      ]
    }
  }
}

#Find and Replace

Replace literal text without any delimiters — the keys are matched verbatim. Useful for rebranding or updating fixed wording. Values use the same Patch shape (paragraph runs or block content):

const result = await patchDocument({
  outputType: "nodebuffer",
  data: templateBuffer,
  findReplace: {
    "Acme Corp": { type: "paragraph", children: [{ text: "Globex", bold: true }] },
    Draft: { type: "paragraph", children: [{ text: "Final" }] },
  },
});

#Core Properties

Override document metadata (docProps/core.xml). Values are merged over the existing core properties — supply only the fields you want to change:

const result = await patchDocument({
  outputType: "nodebuffer",
  data: templateBuffer,
  coreProperties: { title: "Quarterly Report", creator: "Jane Doe" },
});

#Append Content

Append block-level content to the document body, inserted before the final section break (<w:sectPr>). It reuses the same SectionChild vocabulary as "document" patches, so paragraphs, tables, images, and hyperlinks are all supported:

const result = await patchDocument({
  outputType: "nodebuffer",
  data: templateBuffer,
  append: [
    { paragraph: { children: ["Appended paragraph"] } },
    { paragraph: { children: [{ text: "Bold tail", bold: true }] } },
  ],
});

Appended content is serialized through the same compile-path stringifiers as generateDocument, and its images and hyperlinks are wired into the document's relationships automatically. Styles and numbering referenced by appended content must already exist in the template.

#Section Edits

Edit the section list itself — replace a whole section's content or append new sections. Each replacement entry names its 0-based section index (0 = from the document start):

const result = await patchDocument({
  outputType: "nodebuffer",
  data: templateBuffer,
  sections: {
    replace: [
      {
        index: 0,
        section: {
          children: [{ paragraph: { heading: "Heading1", children: ["Chapter 1 — replaced"] } }],
        },
      },
    ],
    append: [
      {
        children: [{ paragraph: { children: ["Appendix"] } }],
        properties: { pageSize: { width: 16838, height: 11906 } },
      },
    ],
  },
});

• Without properties, a replaced section keeps its existing page setup; with properties, the new page setup takes over.
• Appended sections are inserted before the final body sectPr, each closed by its own section break. A section without properties inherits the final section's page setup.
• Children serialize through the same pipeline as append (paragraphs, tables, images, hyperlinks).
• headers/footers are not supported in patched-in sections — they would need new parts; use generateDocument for those.

#Comments

Inject comments into an existing document, merged with any existing word/comments.xml. Comment ids are continued from the highest existing id (or 0 when there are none). Two anchor kinds:

• paragraphs — wrap a comment around the Nth body paragraph (0-based, by document order).
• placeholders — wrap a comment around the run containing a {{key}} token, applied before the placeholder is substituted.

Each comment reuses the CommentOptions vocabulary (see Comments and Revisions) but omits the id — the patch assigns continuation ids automatically.

const result = await patchDocument({
  outputType: "nodebuffer",
  data: templateBuffer,
  comments: {
    paragraphs: [
      {
        index: 0,
        comments: [{ author: "Alice", children: ["Review the opening paragraph."] }],
      },
    ],
    placeholders: {
      name: [{ author: "Bob", children: ["Verify this value."] }],
    },
  },
});

Existing comments are preserved — new entries are appended to word/comments.xml and re-serialized, and the comments relationship and content-type wiring are added when the part is new.

#Custom Delimiters

Default delimiters are {{ and }}. Change them with placeholderDelimiters:

await patchDocument({
  outputType: "nodebuffer",
  data: templateBuffer,
  placeholders: { name: { type: "paragraph", children: [{ text: "John" }] } },
  placeholderDelimiters: { start: "<<", end: ">>" },
});

#Options

#patchDetector

Scan a template to discover all placeholder keys before patching:

import { patchDetector } from "@office-open/docx";

const placeholders = await patchDetector({
  data: readFileSync("template.docx"),
});
// ["name", "title", "content", ...]

#Tips

• Placeholders span across split runs in Word — the library handles this automatically.
• placeholders and findReplace share one engine; combine both in a single call.
• Every occurrence of a placeholder is replaced, not just the first — in the body, headers, and footers alike.
• Use keepOriginalStyles: true (default) to inherit the template's run formatting when replacing text.
• Images and hyperlinks in patch content are automatically added to the document's relationships.