# What changed in @betteroffice/docx

> 51 changes in @betteroffice/docx 0.4 to 0.5 from its official release notes, upgrade guides and advisories: 7 breaking, 21 new APIs and options. Each one cited. Sources checked 2026-10-28. HTML: https://unstale.sh/npm/@betteroffice/docx/

To see which of these apply to a repository, run `npx @unstale/cli init` in it.

## @betteroffice/docx 0.5

### Breaking changes

- Table cell text ignores the section line grid by default to prevent oversized rows; enabling this option retains cell grid snapping. (0.5.1) — [release notes](https://github.com/openooxml/betteroffice/releases/tag/%40betteroffice/docx%400.5.1)
- The document worker file is now named docxWorker.mjs; bundlers that copy or allowlist the worker by name need the new name. (0.5.0) — [release notes](https://github.com/openooxml/betteroffice/releases/tag/%40betteroffice/docx%400.5.0)
- New pictures are locked by default, while explicit unlocks are preserved. (0.5.0) — [release notes](https://github.com/openooxml/betteroffice/releases/tag/%40betteroffice/docx%400.5.0)
- Opening a non-DOCX or malformed package fails instead of showing an empty document. (0.5.0) — [release notes](https://github.com/openooxml/betteroffice/releases/tag/%40betteroffice/docx%400.5.0)
- Picking a paragraph style replaces the old style's text formatting, including text typed into an emptied heading, while preserving direct character formatting. (0.5.0) — [release notes](https://github.com/openooxml/betteroffice/releases/tag/%40betteroffice/docx%400.5.0)
- The former document worker filename is replaced by docxWorker.mjs. (0.5.0) — [release notes](https://github.com/openooxml/betteroffice/releases/tag/%40betteroffice/docx%400.5.0)
- Implementations must add the new members; insertText and deleteRange now return YrsReplaceReceipt, which extends YrsRevisionReceipt. (0.5.0) — [release notes](https://github.com/openooxml/betteroffice/releases/tag/%40betteroffice/docx%400.5.0)

### New APIs and options

- Adds an adapter for experimental collaboration replicas whose state lives in a worker. (0.5.0) — [release notes](https://github.com/openooxml/betteroffice/releases/tag/%40betteroffice/docx%400.5.0)
- Adds a worker editing-session entry point with session creation, command connections, a worker client and command protocol types. (0.5.0) — [release notes](https://github.com/openooxml/betteroffice/releases/tag/%40betteroffice/docx%400.5.0)
- Adds experimental collaboration replicas whose state lives in a worker. (0.5.0) — [release notes](https://github.com/openooxml/betteroffice/releases/tag/%40betteroffice/docx%400.5.0)
- Adds an API for creating a worker command connection. (0.5.0) — [release notes](https://github.com/openooxml/betteroffice/releases/tag/%40betteroffice/docx%400.5.0)
- Adds a worker editing-session creation API. (0.5.0) — [release notes](https://github.com/openooxml/betteroffice/releases/tag/%40betteroffice/docx%400.5.0)
- Adds an opt-in worker client from the worker entry point. (0.5.0) — [release notes](https://github.com/openooxml/betteroffice/releases/tag/%40betteroffice/docx%400.5.0)
- Adds an opt-in edit for inserting section breaks. (0.5.0) — [release notes](https://github.com/openooxml/betteroffice/releases/tag/%40betteroffice/docx%400.5.0)
- DOCX sessions can insert a section break after a position. (0.5.0) — [release notes](https://github.com/openooxml/betteroffice/releases/tag/%40betteroffice/docx%400.5.0)
- DOCX sessions can list document sections. (0.5.0) — [release notes](https://github.com/openooxml/betteroffice/releases/tag/%40betteroffice/docx%400.5.0)
- Adds a session read for listing stories. (0.5.0) — [release notes](https://github.com/openooxml/betteroffice/releases/tag/%40betteroffice/docx%400.5.0)
- Adds an opt-in limit for synchronization size; updates over 64 MiB are refused. (0.5.0) — [release notes](https://github.com/openooxml/betteroffice/releases/tag/%40betteroffice/docx%400.5.0)
- Image models and worker image geometry expose noChangeAspect by default to preserve picture aspect-ratio locks. (0.5.0) — [release notes](https://github.com/openooxml/betteroffice/releases/tag/%40betteroffice/docx%400.5.0)
- Adds section listings to office_outline. (0.5.0) — [release notes](https://github.com/openooxml/betteroffice/releases/tag/%40betteroffice/docx%400.5.0)
- Adds an optional display-only textBox shape. (0.5.0) — [release notes](https://github.com/openooxml/betteroffice/releases/tag/%40betteroffice/docx%400.5.0)
- Adds a session read for reading stories. (0.5.0) — [release notes](https://github.com/openooxml/betteroffice/releases/tag/%40betteroffice/docx%400.5.0)
- Adds a docx_edit operation for replying to comments. (0.5.0) — [release notes](https://github.com/openooxml/betteroffice/releases/tag/%40betteroffice/docx%400.5.0)
- Adds a docx_edit operation for resolving comments. (0.5.0) — [release notes](https://github.com/openooxml/betteroffice/releases/tag/%40betteroffice/docx%400.5.0)
- Adds an opt-in edit for setting section properties. (0.5.0) — [release notes](https://github.com/openooxml/betteroffice/releases/tag/%40betteroffice/docx%400.5.0)
- DOCX sessions can set section starts, orientation, page size and margins. (0.5.0) — [release notes](https://github.com/openooxml/betteroffice/releases/tag/%40betteroffice/docx%400.5.0)
- Adds an opt-in setting for chunked initial synchronization. (0.5.0) — [release notes](https://github.com/openooxml/betteroffice/releases/tag/%40betteroffice/docx%400.5.0)
- Adds a DOCX session API for editing comment metadata. (0.5.0) — [release notes](https://github.com/openooxml/betteroffice/releases/tag/%40betteroffice/docx%400.5.0)

### Performance

- Saving an edited document is faster, especially for documents with many pictures, because the original package is read once per opened document rather than reparsed for each save. (0.5.1) — [release notes](https://github.com/openooxml/betteroffice/releases/tag/%40betteroffice/docx%400.5.1)
- Saving formatting changes in DOCX paragraphs with many short runs is faster. (0.5.1) — [release notes](https://github.com/openooxml/betteroffice/releases/tag/%40betteroffice/docx%400.5.1)

### Behavior and default changes

- Comment cards now match tracked change cards in their header, buttons, reply field, and button styling; resolving, menus, and replies continue to work. (0.5.1) — [release notes](https://github.com/openooxml/betteroffice/releases/tag/%40betteroffice/docx%400.5.1)
- Selawik is now the default for upright Segoe UI families, preserving their weights; italic Segoe UI keeps a real italic fallback face. (0.5.1) — [release notes](https://github.com/openooxml/betteroffice/releases/tag/%40betteroffice/docx%400.5.1)
- The document worker thread now uses this name. (0.5.0) — [release notes](https://github.com/openooxml/betteroffice/releases/tag/%40betteroffice/docx%400.5.0)

### Fixes and other changes

- Edits that rewrite or split DOCX runs preserve authored font slots and language; inserted paragraphs copying a neighbour retain authored fonts without resolved theme fonts or inherited script slots. (0.5.1) — [release notes](https://github.com/openooxml/betteroffice/releases/tag/%40betteroffice/docx%400.5.1)
- Text with automatic color now turns white on dark text boxes, shapes, shaded paragraphs, and shaded runs, and stays black on mid tone table cells, matching Word. (0.5.1) — [release notes](https://github.com/openooxml/betteroffice/releases/tag/%40betteroffice/docx%400.5.1)
- Bar and column data labels now follow PowerPoint and Excel placement for outside end, inside end, inside base, horizontal bars, and stacked charts. (0.5.1) — [release notes](https://github.com/openooxml/betteroffice/releases/tag/%40betteroffice/docx%400.5.1)
- Chart axes now honor tick label positions: none hides labels, high moves them to the far side, and a deleted category axis draws no labels. (0.5.1) — [release notes](https://github.com/openooxml/betteroffice/releases/tag/%40betteroffice/docx%400.5.1)
- When chart data labels do not specify a number format, Word documents now use the format saved with the chart values. (0.5.1) — [release notes](https://github.com/openooxml/betteroffice/releases/tag/%40betteroffice/docx%400.5.1)
- Saving edits preserves plain line breaks, automatic table cell shading, and parent comment reference formatting; replies use the document's comment reference style or inherit the parent's formatting. (0.5.1) — [release notes](https://github.com/openooxml/betteroffice/releases/tag/%40betteroffice/docx%400.5.1)
- Saving DOCX files removes text-only runs emptied by direct text edits while preserving runs that were already empty or contain other content. (0.5.1) — [release notes](https://github.com/openooxml/betteroffice/releases/tag/%40betteroffice/docx%400.5.1)
- Documents now lay out every page when font downloads fail or no font provider is configured, wrapping long paragraphs on fallback metrics and logging the warning once per editor. (0.5.1) — [release notes](https://github.com/openooxml/betteroffice/releases/tag/%40betteroffice/docx%400.5.1)
- Paragraph reads now include resolved outline levels and list markers in accepted and original views. (0.5.1) — [release notes](https://github.com/openooxml/betteroffice/releases/tag/%40betteroffice/docx%400.5.1)
- Pie and doughnut data labels now follow PowerPoint and Excel placement for slices, best fit, outside end, and doughnut rings. (0.5.1) — [release notes](https://github.com/openooxml/betteroffice/releases/tag/%40betteroffice/docx%400.5.1)
- Adds Office-aware fallback coverage for characters absent from Selawik in Word and PowerPoint previews. (0.5.1) — [release notes](https://github.com/openooxml/betteroffice/releases/tag/%40betteroffice/docx%400.5.1)
- Adds Office-aware fallback coverage for characters absent from Selawik in Word and PowerPoint previews. (0.5.1) — [release notes](https://github.com/openooxml/betteroffice/releases/tag/%40betteroffice/docx%400.5.1)
- Segoe UI Light, Semilight, and Semibold now use Word's line height; Light and Semilight retain Word's narrower letter widths, improving page-break alignment. (0.5.1) — [release notes](https://github.com/openooxml/betteroffice/releases/tag/%40betteroffice/docx%400.5.1)
- Story reads now report header and footer visibility when a complete layout of the current version is available. (0.5.1) — [release notes](https://github.com/openooxml/betteroffice/releases/tag/%40betteroffice/docx%400.5.1)
- Zero-valued bar and column labels now sit on the side indicated by the value axis, including when the axis is reversed. (0.5.1) — [release notes](https://github.com/openooxml/betteroffice/releases/tag/%40betteroffice/docx%400.5.1)
- At the end of a heading, Enter starts the next paragraph in the heading style's next style; inside a heading it keeps the heading style. (0.5.0) — [release notes](https://github.com/openooxml/betteroffice/releases/tag/%40betteroffice/docx%400.5.0)
- The toolbar now lists paragraph styles and fonts when opened from a parsed document via the document prop or loadDocument. (0.5.0) — [release notes](https://github.com/openooxml/betteroffice/releases/tag/%40betteroffice/docx%400.5.0)

## @betteroffice/docx 0.4

### Performance

- Documents open faster, especially ones with many comments. (0.4.3) — [release notes](https://github.com/openooxml/betteroffice/releases/tag/%40betteroffice/docx%400.4.3)