NPM Packages: Upgrading from 0.x to v1

The @topol.io/editor packages jump from 0.3.0 to 1.0.0-alpha.x. This guide explains why the major bump happened, what is new, and what existing 0.x integrations need to review before upgrading.

Install the alpha with:

JS / TS

npm install @topol.io/editor@alpha

React

npm install @topol.io/editor-react@alpha

Vue

npm install @topol.io/editor-vue@alpha

Svelte

npm install @topol.io/editor-svelte@alpha

v1 is in alpha

We do not expect major changes to the API before the final v1 release, but details can still move. Pin the exact version you integrate against and read the changelog before upgrading.

Let an AI agent do the upgrade

TOPOL-io/skills has two skills for coding agents, written as plain markdown. topol-editor-integration sets up either editor in a new project and topol-v1-upgrade moves an existing integration from 0.x to v1. They install as a Claude Code plugin (/plugin marketplace add TOPOL-io/skills) or into any agent with npx skills@latest add TOPOL-io/skills.

The headline: Landing Page Editor support

Until 0.3.0, the packages covered only the Email Editor. v1 makes them the integration point for both Topol editors:

• @topol.io/editor now exports LandingPageEditor alongside the email editor, with full TypeScript types for the Landing Page Editor options, callbacks, and template structure.
• @topol.io/editor-react and @topol.io/editor-vue gain a LandingPageEditor component with the complete callback set and programmatic load/save via ref.
• @topol.io/editor-svelte does not include a Landing Page Editor component yet — it only picks up the Email Editor improvements below.

Usage is documented in the Landing Page Editor NPM integration guide.

Renames and deprecations

Backwards compatible, but on a removal path:

• The email integration is now called EmailEditor. The old names keep working as deprecated aliases:
  • core: TopolPlugin → EmailEditor
  • React / Vue: the TopolEditor component → EmailEditor (the old component logs a console deprecation warning on mount)
  • Svelte keeps the TopolEditor name for now.

Migration is a rename:

- import TopolPlugin from "@topol.io/editor";
+ import { EmailEditor } from "@topol.io/editor";

- await TopolPlugin.init(options);
+ await EmailEditor.init(options);

Changes existing 0.3.0 integrations should review

• onSave and onSaveAndClose grew two parameters for multilingual template support: (json, html, mutations, syncedSections) instead of (json, html). Framework wrapper events include mutations and syncedSections in their payload objects. Existing two-argument handlers keep working, but code that spreads or strictly types the payload will notice.
• onError gained a third parameter, responseBody, so error handlers can inspect the failing API response. Wrapper event payloads include it too.
• Loader URLs are now hard-coded as canonical defaults instead of coming from build-time environment variables. This fixes a 0.x bug where a build without those variables produced <script src="undefined">. The stage resolver now falls back to the production loader — or throws a clear error — instead of silently injecting a broken script tag.

New Email Editor API surface

New methods on the plugin, exposed through all wrappers:

Method	Purpose
save(lang?)	Save a specific language mutation
createLanguage, deleteLanguage, selectLanguage, setPrimaryLanguage, getMutations	Multilingual template management
updateOptions(partialOptions)	Change editor options after init
updateTemplate(json, { skipSnapshot })	Replace the template programmatically
toggleControlPanel()	Show/hide the control panel
toggleDarkMode()	Toggle the dark mode preview

New callbacks, exposed as events in the wrappers:

• onLanguageCreated(lang, mutations)
• onLanguageDeleted(lang, mutations)
• onLanguageSelected(lang)
• onPrimaryLanguageChanged(lang, mutations)
• onGetMutations(mutations)

Plus general type updates and assorted fixes accumulated through the earlier 1.0.0-alpha pre-releases.

INFO

Running into trouble while upgrading? Contact our support team here and we'll help you get it working.