Migration: 0.x → 1.x

What moved where

0.x was a single package. 1.x splits it into five, by concern:

In practice a React app still imports from one package, @eigenpal/docx-editor-react, which pulls in -core and -i18n for you. You only name the other packages when you import the document model, the agent toolkit, or locale data directly. The rest of this guide is the symbol-level detail behind that split.

TL;DR

1. Install the new package set (-react or -vue, plus -core and -agents if you need them).
2. Update the symbols whose home changed across packages first (see Moved symbols), a plain package-name swap leaves them unresolved.
3. Change every remaining @eigenpal/docx-js-editor import to @eigenpal/docx-editor-react.
4. Rename FormattingBar → Toolbar and Toolbar (composite) → EditorToolbar.
5. Remove showPrintButton from <DocxEditor> and toolbar props (deleted in 1.0).
6. Rewire i18n imports, locales are named exports now, not subpath JSON files.
7. License changes: every package is now Apache 2.0 (the agents package was AGPL-3.0).

The mechanical work is small but the moved symbols catch people. Read Moved symbols before you start updating imports.

Package renames

The monolithic @eigenpal/docx-js-editor split into five packages under the @eigenpal/docx-editor-* namespace.

Install the package set you actually use:

# Bare minimum for a React editor:
npm uninstall @eigenpal/docx-js-editor
npm install @eigenpal/docx-editor-react
 
# Vue 3 instead:
npm install @eigenpal/docx-editor-vue
 
# Add the agent toolkit (also where the agent UI components live now):
npm install @eigenpal/docx-editor-agents
 
# Standalone i18n (transitively installed by -react and -vue):
npm install @eigenpal/docx-editor-i18n

-core and -i18n are pulled in transitively by -react and -vue. Install them explicitly only when you import directly from those packages.

Moved symbols

Five categories of symbols moved across packages (not just subpaths). A plain package-name swap to @eigenpal/docx-editor-react won't resolve these. If a symbol from this list lives in your code, point its import at the new home below, otherwise you'll get a wall of "no exported member" errors.

Why these moved. Agent UI primitives ship with the toolkit they pair with, not with the editor. Plugin types live next to the plugin contract. Document types and createEmptyDocument are declared in -core (framework-agnostic); 1.0.1 re-exports createEmptyDocument/createDocumentWithText from -react and -vue so most apps don't need a separate -core install, and surfaces the common document-tree types at the -core root entry so the deep -core/headless subpath only matters for the long tail.

Pin to ≥1.0.1. Earlier 1.0.0 required importing createEmptyDocument from @eigenpal/docx-editor-core (a separate install) and document types from @eigenpal/docx-editor-core/headless (an unguessable subpath). 1.0.1 fixed both. If you're on 1.0.0, upgrade the patch version before migrating; it removes most of the import-pain in this guide.

You don't need a script for this. TypeScript will point you at each one: a moved symbol that's still importing from the old package shows up as a Module has no exported member error, and the table above gives its new home. Fix them as they come up.

Remaining imports

Once the moved symbols are handled, every remaining @eigenpal/docx-js-editor import changes to @eigenpal/docx-editor-react. Only the package name changes; the imported names stay the same.

A few 0.x subpaths don't live under -react and need a different package:

API renames

FormattingBar → Toolbar

What was previously called the "formatting bar" is now Toolbar, a closer name to what it actually is.

- import { FormattingBar } from "@eigenpal/docx-js-editor";
+ import { Toolbar } from "@eigenpal/docx-editor-react/ui";

Toolbar (composite) → EditorToolbar

The old Toolbar that combined a menu bar + the formatting buttons is now EditorToolbar. The formatting strip on its own is Toolbar. The lower-level pieces (ToolbarButton, ToolbarGroup, ToolbarSeparator, ResponsiveToolbar) are exported alongside.

- import { Toolbar } from "@eigenpal/docx-js-editor";
+ import { EditorToolbar } from "@eigenpal/docx-editor-react/ui";
// or compose your own:
+ import { Toolbar, ToolbarButton, ToolbarGroup } from "@eigenpal/docx-editor-react/ui";

If you want the same behavior as 0.x's Toolbar, use EditorToolbar. If you want only the formatting buttons (what 0.x called FormattingBar), use the new Toolbar.

MenuBar from 0.x is gone in 1.x. Compose your own from ToolbarButton and ToolbarGroup, or use EditorToolbar which includes a menu strip by default.

Removed APIs

showPrintButton

Removed from <DocxEditor> and the toolbar. Render your own button if you need it.

- <DocxEditor documentBuffer={buf} showPrintButton />
+ <DocxEditor documentBuffer={buf} />

i18n restructure

The package changed name (-i18n is now standalone) and gained two import styles. Both are supported in 1.0.1+.

Locales: subpath or named export

The 1.0 release shipped named exports only and broke per-locale code splitting in the process. 1.0.1 restored subpath exports, so you can pick:

// Subpath, bundlers tree-shake to just this locale's strings. Best for dynamic loading.
import pl from "@eigenpal/docx-editor-i18n/pl";
 
// Named, drops the dash for camelCase. Best for static "load all known locales" lists.
import { pl, ptBR } from "@eigenpal/docx-editor-i18n";

The diff from 0.x:

- import pl from "@eigenpal/docx-js-editor/i18n/pl.json";
+ import pl from "@eigenpal/docx-editor-i18n/pl";

Locale codes

Dynamic locale imports

Path-templated dynamic imports work the same shape as before, just against the new package:

- import(`@eigenpal/docx-js-editor/i18n/${locale}.json`).then(setI18n);
+ import(`@eigenpal/docx-editor-i18n/${locale}`).then((m) => setI18n(m.default));

Each subpath emits its own chunk, so the bundler ships only the locale that loaded.

TypeScript types

In 0.x each locale's type was the inferred typeof <json>, concrete and indistinguishable from one another. In 1.x, only en is the source-of-truth LocaleStrings; the others are PartialLocaleStrings (some keys may be missing). Update your local type unions:

- type LocaleI18n = typeof pl | typeof de | undefined;
+ import type { LocaleStrings, PartialLocaleStrings } from "@eigenpal/docx-editor-i18n";
+ type LocaleI18n = LocaleStrings | PartialLocaleStrings | undefined;

License change

The 0.x line of @eigenpal/docx-editor-agents was AGPL-3.0. In 1.0, all five packages are Apache 2.0. If you tracked license obligations for compliance review, update the entry. Apache 2.0 is permissive: no copyleft on derivative works.

The non-agents packages (-core, -react, -vue, -i18n) were also previously AGPL through @eigenpal/docx-js-editor; they're now Apache 2.0 as well.

Vue users

Vue 3 is a published adapter in 1.0; it didn't exist in 0.x. If you were embedding the editor in a Vue app via the React adapter + a wrapper, drop the wrapper and use @eigenpal/docx-editor-vue directly. The surface mirrors React (same component name, hooks-as-composables, same plugin contract). Cross-adapter parity is enforced by etc/parity.contract.json upstream. See the Vue package page.

Verifying the migration

1. TypeScript first. TypeScript will flag every moved symbol with a Module has no exported member error. Those are your roadmap to the Moved symbols table.
2. Build the project. next build / vite build catches dynamic-import path errors that TS misses.
3. Run your test suite. The behavior of every preserved API is unchanged; tests are the safety net for the import changes.
4. Check the editor visually for the missing print button and any toolbar configuration you used to pass via showPrintButton.

If something behaves differently and isn't covered above, it's likely a bug rather than an intended change, please file an issue in the docx-editor repo.

Where to go next

• Installation, framework-specific setup for 1.x
• Package overview, which package does what
• API reference, every export, generated from upstream types
• 0.x archive, your old docs are still here if you need them