npm / @betteroffice/docx
@betteroffice/docx
What changed in @betteroffice/docx 0.4 to 0.5, from its official release notes, upgrade guides and advisories. Sources checked 2026-10-28.
7 breaking21 new APIs and options3 performance3 behavior and defaults17 fixes and other
See which of these apply to your code, ranked, in your agent:
npx @unstale/cli init@betteroffice/docx 0.550 changes
Breaking changes 7
Table cell text ignores the section line grid by default to prevent oversized rows; enabling this option retains cell grid snapping.
The document worker file is now named docxWorker.mjs; bundlers that copy or allowlist the worker by name need the new name.
New pictures are locked by default, while explicit unlocks are preserved.
Opening a non-DOCX or malformed package fails instead of showing an empty document.
Picking a paragraph style replaces the old style's text formatting, including text typed into an emptied heading, while preserving direct character formatting.
The former document worker filename is replaced by docxWorker.mjs.
Implementations must add the new members; insertText and deleteRange now return YrsReplaceReceipt, which extends YrsRevisionReceipt.
New APIs and options 21
Adds an adapter for experimental collaboration replicas whose state lives in a worker.
Adds a worker editing-session entry point with session creation, command connections, a worker client and command protocol types.
Adds experimental collaboration replicas whose state lives in a worker.
Adds an API for creating a worker command connection.
Adds a worker editing-session creation API.
Adds an opt-in worker client from the worker entry point.
Adds an opt-in edit for inserting section breaks.
DOCX sessions can insert a section break after a position.
DOCX sessions can list document sections.
Adds a session read for listing stories.
Adds an opt-in limit for synchronization size; updates over 64 MiB are refused.
Image models and worker image geometry expose noChangeAspect by default to preserve picture aspect-ratio locks.
Adds section listings to office_outline.
Adds an optional display-only textBox shape.
Adds a session read for reading stories.
Adds a docx_edit operation for replying to comments.
Adds a docx_edit operation for resolving comments.
Adds an opt-in edit for setting section properties.
DOCX sessions can set section starts, orientation, page size and margins.
Adds an opt-in setting for chunked initial synchronization.
Adds a DOCX session API for editing comment metadata.
Performance 2
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.
Saving formatting changes in DOCX paragraphs with many short runs is faster.
Behavior and default changes 3
Comment cards now match tracked change cards in their header, buttons, reply field, and button styling; resolving, menus, and replies continue to work.
Selawik is now the default for upright Segoe UI families, preserving their weights; italic Segoe UI keeps a real italic fallback face.
The document worker thread now uses this name.
Fixes and other changes 17
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.
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.
Bar and column data labels now follow PowerPoint and Excel placement for outside end, inside end, inside base, horizontal bars, and stacked charts.
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.
When chart data labels do not specify a number format, Word documents now use the format saved with the chart values.
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.
Saving DOCX files removes text-only runs emptied by direct text edits while preserving runs that were already empty or contain other content.
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.
Paragraph reads now include resolved outline levels and list markers in accepted and original views.
Pie and doughnut data labels now follow PowerPoint and Excel placement for slices, best fit, outside end, and doughnut rings.
Adds Office-aware fallback coverage for characters absent from Selawik in Word and PowerPoint previews.
Adds Office-aware fallback coverage for characters absent from Selawik in Word and PowerPoint previews.
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.
Story reads now report header and footer visibility when a complete layout of the current version is available.
Zero-valued bar and column labels now sit on the side indicated by the value axis, including when the axis is reversed.
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.
The toolbar now lists paragraph styles and fonts when opened from a parsed document via the document prop or loadDocument.
@betteroffice/docx 0.41 changes
Performance 1
Documents open faster, especially ones with many comments.