Migration: 0.x → 1.x

TL;DR

1. Install the new package set (-react or -vue, plus -core and -agents if you need them).
2. Move symbols whose home changed across packages first (see Moved symbols), the bulk find/replace recipe below assumes you've already handled these.
3. Run the bulk codemod to swap @eigenpal/docx-js-editor → @eigenpal/docx-editor-react everywhere else.
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 reaching for the codemod.

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). The bulk codemod below routes everything to @eigenpal/docx-editor-react. If a symbol from this list lives in your code, fix its import first, 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.

Run these greps first to find the affected lines, then update each import block by hand or with a per-symbol sed:

# createEmptyDocument
grep -rn 'createEmptyDocument' src/
 
# Document tree types, the most common: Comment
grep -rn "import type {[^}]*\bComment\b[^}]*} from ['\"]@eigenpal/docx-js-editor" src/
 
# Agent UI components
grep -rEn "AgentPanel|AgentChatLog|AgentComposer|AgentSuggestionChip|AgentTimeline" src/
 
# Plugin host / template plugin
grep -rEn 'PluginHost|templatePlugin' src/

Targeted sed examples for each category:

# Route createEmptyDocument to -core (do this BEFORE the bulk codemod):
grep -rl 'createEmptyDocument' src/ | xargs sed -i '' \
  -E 's|import \{ ([^}]*)createEmptyDocument([^}]*)\} from "@eigenpal/docx-js-editor"|import { \1createEmptyDocument\2} from "@eigenpal/docx-editor-core"|'
 
# Route Comment type to -core/headless (also do this BEFORE the bulk codemod):
grep -rl 'import type {[^}]*Comment[^}]*}' src/ | xargs sed -i '' \
  's|from "@eigenpal/docx-js-editor"|from "@eigenpal/docx-editor-core/headless"|'

These regex sed lines are starting points, review the diff before committing. A real codemod (jscodeshift / ts-morph) would do this safely; one isn't shipped with 1.0.

Bulk codemod (run after the moved-symbol fixups)

For every remaining import:

# From the root of your project:
grep -rl '@eigenpal/docx-js-editor' src/ \
  | xargs sed -i '' 's|@eigenpal/docx-js-editor|@eigenpal/docx-editor-react|g'

Then fix the legacy subpath edge cases (these are leftover from 0.x's monorepo-style subpath layout):

grep -rn 'docx-editor-react/core' src/    # → @eigenpal/docx-editor-core
grep -rn 'docx-editor-react/mcp' src/     # → @eigenpal/docx-editor-agents/mcp
grep -rn 'docx-editor-react/i18n' src/    # → see "i18n restructure" below

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 bulk codemod.
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