Skip to main content

Migration Guide

This page documents breaking changes between SDK major versions and the steps to migrate existing extensions.

Current version​

The current SDK major version is v1. This is the initial stable release. No migrations are required for extensions created with @zaflun/lumio-sdk@^1.0.0.

Future migrations​

When a new major version is released, this page will be updated with:

  • The full list of breaking changes
  • Automated codemod scripts where available
  • Step-by-step manual migration instructions
  • A migration deadline (how long the previous version will continue to receive bug fixes)

Staying current​

Watch the @zaflun/lumio-sdk release history on npm to be notified when new versions are published.

The lumio status CLI command also shows whether your extension's SDK version is current:

lumio status
Extension: Sports Scoreboard (ext_01j9k2m3n4p5q6r7)
Status:    approved
Version:   1.2.0
SDK:       @zaflun/[email protected]  ✓  (latest)

Deprecation policy​

Before any breaking change is shipped:

  1. The deprecated API is marked in the TypeScript types with a @deprecated JSDoc tag
  2. The runtime emits a console.warn when the deprecated API is used in dev mode
  3. A migration guide entry is published at least 3 months before removal
  4. The CLI prints a warning during lumio build if deprecated APIs are detected

Reporting compatibility issues​

If you find that an SDK update broke your extension in an undocumented way, file a bug report in the developer portal with:

  • Your SDK version (package.json → @zaflun/lumio-sdk)
  • The previous SDK version where it worked
  • A minimal reproduction case

We treat unannounced breaking changes as bugs and aim to fix them within 48 hours.