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​

Subscribe to the Lumio Developer Newsletter or watch the GitHub releases page to be notified when new versions are released.

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/lumio-sdk@1.0.0  ✓  (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.