Upgrading

Upgrade the SDK, Module Federation packages, and host compatibility declaration as separate decisions. A dependency install that succeeds does not prove a package can activate on every supported host.

Review the Public Contract

Read the SDK release notes and compare the API reference with the imports used by your package. Check:

  • removed or renamed exports;
  • new required fields or stricter validation in config-schema.json;
  • changed peer dependency ranges;
  • newly optional or newly required host capabilities; and
  • target runtime or emitted-manifest changes.

Upgrade in One Change

Update @theaiplatform/miniapp-sdk and keep all directly installed Module Federation packages on one exact supported version. Update the lockfile in the same change.

Do not widen compatibility.tapSdk or compatibility.tapHost until the new build has passed clean package and host validation.

Rebuild from Clean Staging Roots

Remove old target staging output and rebuild every declared target. Then assemble a new immutable release and run the portability scan.

Compare the emitted descriptor and Federation manifests with the prior release. Expected changes should be explainable by the SDK or source update.

Validate in Development

Publish the new immutable release to a development environment while production remains on the prior tested release. Verify:

  • every target imports successfully;
  • required and optional capabilities behave as documented;
  • mounted surfaces clean up correctly;
  • compatible state survives fresh-realm activation;
  • a rollback restores the prior release; and
  • a failed candidate does not displace the last known good release.

Promote the already tested immutable release. Do not rebuild it during promotion.

Handle a Breaking Upgrade

For a breaking SDK or host contract:

  1. publish a new package release with a narrow compatibility range;
  2. migrate persisted data through an explicit versioned path;
  3. retain only documented, time-bounded compatibility aliases;
  4. test old and new supported host ranges separately; and
  5. remove the old path only after supported installations have migrated.

Never use a display-name change to create a second package identity unintentionally.