docxgo

A Go library for creating and editing Microsoft Word (.docx / OOXML) documents, with a JSON-RPC CLI and Node.js wrapper for use from other languages.

🌐 Official Website: docxgo.dev

Installation

Go library:

go get github.com/mmonterroca/docxgo/v2

Node.js / CLI:

npm install @mmonterroca/docxgo

Quick Start (Go)

Builder API (fluent, recommended)

package main
import (
    "log"
    docx "github.com/mmonterroca/docxgo/v2"
    "github.com/mmonterroca/docxgo/v2/domain"
)
func main() {
    builder := docx.NewDocumentBuilder(
        docx.WithTitle("My Report"),
        docx.WithAuthor("John Doe"),
        docx.WithDefaultFont("Calibri"),
        docx.WithPageSize(docx.A4),
        docx.WithLanguage("en-US"), // spell-check, grammar, hyphenation
    )
builder.AddParagraph().
        Text("Project Report").Bold().FontSize(16).
        Color(docx.Blue).Alignment(domain.AlignmentCenter).
        End()
builder.AddParagraph().
        Text("This is bold text").Bold().
        Text(" and this is ").
        Text("colored text").Color(docx.Red).
        End()
doc, err := builder.Build()
    if err != nil {
        log.Fatal(err)
    }
    if err := doc.SaveAs("report.docx"); err != nil {
        log.Fatal(err)
    }
}

The lower-level domain API is also available directly (doc := docx.NewDocument(), doc.AddParagraph(), …) when you want fine-grained control.

Read & modify an existing document

doc, err := docx.OpenDocument("template.docx")
if err != nil {
    log.Fatal(err)
}
for _, para := range doc.Paragraphs() {
    for _, run := range para.Runs() {
        if run.Text() == "PLACEHOLDER" {
            run.SetText("Updated Value")
            run.SetBold(true)
        }
    }
}
if err := doc.SaveAs("modified.docx"); err != nil {
    log.Fatal(err)
}

Node.js & CLI

docxgo ships a JSON-RPC binary (cmd/docxgo) that speaks over stdin/stdout, plus a fully-typed Node.js wrapper built on top of it. Documents can be created and manipulated from any language — with file or base64/buffer I/O, so binaries never have to touch the filesystem.

import { DocumentBuilder } from '@mmonterroca/docxgo';
const doc = new DocumentBuilder();
await doc
  .setOptions({ title: 'Report', author: 'docxgo' })
  .addHeading('Quarterly Report', 1)
  .addParagraph('Generated from Node.js.')
  .createToFile('report.docx');
doc.dispose();

The wrapper offers three API levels — DocxgoExec (one-shot), DocxgoRPC (persistent), and DocumentBuilder (fluent). The binary itself has two modes: docxgo exec (single request) and docxgo rpc (persistent NDJSON session), ideal for batch work and AWS Lambda.

• docs/CLI_GUIDE.md — full JSON-RPC protocol and method reference
• npm/README.md — Node.js API reference and examples

Examples

The examples/ directory has 15 runnable Go programs:

| | | | |---|---|---| | 01_basic — builder basics | 06_sections — page layout | 11_multi_section — multi-section | | 02_intermediate — product catalog | 07_advanced — everything combined | 12_read_and_modify — edit existing | | 03_toc — table of contents | 08_images — images | 13_themes — theme system | | 04_fields — TOC, page numbers, links | 09_advanced_tables — merging, nesting | 14_mail_merge — template engine | | 05_styles — style system | 10_paragraph_spacing — spacing | 15_external_template — MERGEFIELD |

Node.js examples live in npm/examples/.

Architecture

Clean architecture with clear layer boundaries — domain/ (public interfaces), internal/ (implementations), pkg/ (utilities), themes/, plus the cmd/docxgo/ CLI binary and npm/ Node.js wrapper. Interface segregation, dependency injection, explicit errors, a strongly typed public API, and thread-safe internal managers (a single Document is not thread-safe — guard concurrent access; see the package godoc's Thread Safety section). See docs/V2_DESIGN.md for the full rationale.

Error Handling

Every operation returns explicit, structured errors carrying operation context and an error code — no silent failures. The fluent builder accumulates errors and surfaces the first at Build(). See docs/ERROR_HANDLING.md for the error system and patterns.

Testing

go test ./...              # run all tests
go test -cover ./...       # with coverage
go test -bench=. ./...     # benchmarks

Coverage varies by package — domain and pkg/errors are at 100%, internal/xml ~96%, and the core packages sit around 50–70%.

Documentation

• V2 API Guide — complete API reference with examples (start here)
• CLI Guide — JSON-RPC protocol for the CLI / Node.js wrapper
• Node.js wrapper — @mmonterroca/docxgo API reference
• Implementation Status — what's implemented and planned
• Migration Guide — upgrading from v1
• V2 Design · Error Handling · Contributing
• API Reference (pkg.go.dev)

Contributing

Contributions are welcome — see CONTRIBUTING.md for the development workflow (feature branches → master), testing requirements, and PR process. In short: fork, branch from master, add tests, run go test ./..., and open a PR against master.

License & Credits

docxgo v2 is distributed under the MIT license (LICENSE). Its Git history descends from fumiama/go-docx and includes AGPL-era upstream snapshots; the completed provenance audit determines that the current rewritten release contains no protectable AGPL implementation. Historical commits retain their original licenses. See CREDITS.md for the full genealogy.

Support

• Support: GitHub Issues for bugs, questions, and feature requests
• Email: [email protected]