Migrate from v2 to v3 (beta)

This guide is for applications using stable v2.

For a new project, start with Getting started.

Install the beta

Install Ignite with the source library your application uses:

pnpm add ignite-element@beta xstate

For Redux, replace xstate with @reduxjs/toolkit.

For MobX, replace it with mobx.

State libraries and lit-html are optional peers in v3.

The facade installs its internal @ignite-element packages automatically.

Keep importing igniteCore from the entrypoint for your source, such as ignite-element/xstate.

Use ES modules

v3 is native ESM-only.

Replace CommonJS require calls with ES module imports.

See Compatibility for supported toolchains and declaration-resolution limits.

Update command callbacks

The v2 command context exposed actor, emit, and host.

In v3, commands receive source, the active instance’s command interface.

For a callback that only sends an XState event, update it as follows:

commands: ({ actor }) => ({
  toggle: () => actor.send({ type: "TOGGLE" }),
commands: ({ source }) => ({
  toggle: () => source.send({ type: "TOGGLE" }),
})

Pass presentation-specific values as command arguments instead of reading host in the callback.

Move outward event production out of commands.

Use native source events for occurrences and effects for notifications derived from state changes.

The command emission guide shows how to preserve command input and repeated occurrences.

Keep states for derived values; v2 already supported this callback.

See Sources for each adapter’s snapshot and command shapes.

Update configuration imports

The v2 ignite-element/config/* and ignite-element/renderers/* entrypoints are not public v3 entrypoints.

Remove igniteConfigVitePlugin() or IgniteConfigWebpackPlugin from your bundler setup.

The v3 public API does not include these config-loader plugins.

For Ignite JSX, use the compiler settings and component-local CSS shown in Getting started.

If your ignite.config.ts only selected the default JSX renderer, remove that file and its imports.

Preserve any shared stylesheet or renderer settings your application still needs.

For those settings, import defineIgniteConfig from @ignite-element/renderer and load the settings module explicitly before registering components.

The filename ignite.config.ts has no special loading behavior in v3.

For Lit, import @ignite-element/renderer/lit before registering components.

For an existing application retaining these settings or Lit templates, see Renderer compatibility.

Use Ignite JSX and component-local styles for new components.

Check behavior and ownership

Run TypeScript checks and the application’s behavior and DOM tests.

Verify declared events, their payloads, and listeners using Events & effects.

Keep source construction and native shutdown at the application boundary.

Use Ownership & cleanup to review shared sources, isolated instances, and terminal disposal.

The Testing guide shows source, core, and rendered-control assertions.