Upgrade Your App's OS Version Compatibility

Vega OS 2.0 introduces a real multi-version app compatibility workflow. Your app can target OS 2.0 while either requiring OS 2.0 or continuing to support devices on an earlier OS version. The SDK 2.0 tools use the range in your app’s manifest.toml to:

Resolve compatible @amazon-devices/* package versions.
Find JavaScript and TypeScript API usage that is unavailable on your minimum OS version.
Find incompatible OmniKit Interface Definition Language (IDL) interface usage.
Validate removed and deprecated APIs before you build.
Generate OS version module metadata in the packaged app at build time.

Choose the OS versions your app supports

Set both min and target in manifest.toml. For SDK 2.0, set both values to 2.0 (recommended):

[os.version]
min = "2.0"
target = "2.0"

If your app targets OS 2.0 and also needs to support OS 1.2:

[os.version]
min = "1.2"
target = "2.0"

min is the oldest OS version on which the app must install and run.
target is the newest OS version whose APIs and package profile the app builds against.

Only versions listed by the installed SDK are valid. The lowest valid min is 1.2. OS 1.1 isn’t a valid value. Run vega project doctor if you’re unsure which versions are available.

Choose min

For SDK 2.0, set min = "2.0" for new apps and for apps you migrate from an earlier SDK. All Vega devices in the field run OS 2.0, so an OS 2.0-only app reaches the same devices as an app with min = "1.2". With min and target both set to 2.0, you don’t need compatibility guards for OS 2.0 APIs, and you test against one OS version instead of two. Setting min = "1.2" doesn’t reach more devices today. It adds work: you must guard every API introduced after OS 1.2, provide fallbacks, and test on both ends of the range. In future SDK releases, devices in the field might run different OS versions. Then, base min on the oldest OS version that runs on the devices you want to support. The following examples show how to apply this guidance:

A WebView app that uses no OS-specific APIs. Set min = "2.0". A WebView app rarely depends on OS capabilities, so min has little effect on how it runs, but 2.0 is still the recommended value for SDK 2.0.
An app that uses an API introduced in OS 2.0. Set min = "2.0". The API is available on every device your app supports, so you can call it without an isPresentOnOS guard. If you set min = "1.2" instead, you must guard the call and provide a fallback for OS 1.2. For an example, see JavaScript and TypeScript compatibility lint.

Upgrade an existing app to target OS 2.0

From the app project root:

vega project update-manifest --os-min 2.0 --os-version 2.0
vega project install --fix
npm install
vega project doctor
npx react-native build-vega

To support OS 1.2 as well, use --os-min 1.2 instead. For help choosing, see Choose min. Replace npm install and the build command with the package manager and build script your project uses. vega project update-manifest writes the [os.version] values. In SDK 2.0 it also removes any OS version module entries it finds in the source manifest.toml. These are the reserved /com.amazon.vega.os@IVega_* family, and versioned @amzn/<pkg>@<version> and @amazon-devices/<pkg>@<version> module IDs. Removal is based on the module ID’s shape, not on whether you added it by hand or a tool generated it. Don’t re-add one of these IDs to work around the cleanup. On an application project, vega build inserts the required OS module metadata into the packaged manifest instead. On a native project, vega build writes these entries into your source manifest.toml. For details, see OS version module entries in a native project. Dependency module entries that don’t match these ID shapes are preserved.

Migrate from SDK 0.23 or earlier

Apps built with SDK 0.21, 0.22, or 0.23 don’t have an [os.version] section, because the section didn’t exist before SDK 0.24. Those SDK versions shipped with OS 1.1. Starting with SDK 0.24, the section is required, so when you build one of these apps with SDK 2.0, the build fails with a Missing [os.version] error until you add it.

Choose min for an app that ran on OS 1.1

OS 1.1 isn’t a valid min value. The lowest valid min is 1.2. For SDK 2.0, set min to 2.0. For the reasons, see Choose min. Raising min above OS 1.1 doesn’t strand your existing users. Every device in the field that runs OS 1.1 is eligible to update to OS 2.0, and a device that hasn’t updated yet updates its OS before it updates your app.

Add the section and re-align your project

Install SDK 2.0. For instructions, see Manage Your SDK Versions.
Commit your current manifest.toml and package.json, so you can review the changes that the next steps make.
From the app project root, add the [os.version] section, re-align your @amazon-devices/* dependencies, and confirm that the project is compatible:
vega project update-manifest --os-min 2.0 --os-version 2.0 vega project install --fix npm install vega project doctor
To support OS 1.2 as well, use --os-min 1.2 instead.
Build your app:
npx react-native build-vega
Review and commit the changes to manifest.toml and package.json.

SDK 2.0 supports both React Native 0.72 and 0.83, so you don’t need to migrate your app to React Native 0.83 to build it with SDK 2.0. To migrate, see Migrate Apps to React Native 0.83.

Example manifest before and after

A manifest.toml from an SDK 0.22 app has no [os.version] section:

schema-version = 1

[package]
id = "com.example.myapp"
title = "My App"

[components]
[[components.interactive]]
id = "com.example.myapp.main"
runtime-module = "/com.amazon.kepler.keplerscript.runtime.loader_2@IKeplerScript_2_0"
launch-type = "singleton"
categories = ["com.amazon.category.main"]

After you run vega project update-manifest --os-min 2.0 --os-version 2.0, the manifest has an [os.version] section:

schema-version = 1

[package]
id = "com.example.myapp"
title = "My App"

[os.version]
target = "2.0"
min = "2.0"

[components]
[[components.interactive]]
id = "com.example.myapp.main"
runtime-module = "/com.amazon.kepler.keplerscript.runtime.loader_2@IKeplerScript_2_0"
launch-type = "singleton"
categories = ["com.amazon.category.main"]

JavaScript and TypeScript compatibility lint

When min is lower than target, an API introduced after min might not exist on every supported device. SDK 2.0 checks source usage against the installed compatibility manifest. The compatibility rules report the following.

Rule	Result	What to do
`no-unguarded-os-api`	Error	Guard an API introduced after `min`, provide a fallback, or raise `min`.
`no-removed-api`	Error	Replace an API that was removed at or before `min`.
`warn-deprecated-api`	Warning	Migrate away from an API deprecated at or before `target`.

For an app with min = "1.2" and target = "2.0", guard an API that was added in OS 2.0:

import { isPresentOnOS } from '@amazon-devices/kepler-compatibility';
import * as FileSystem from '@amazon-devices/kepler-file-system';

function saveSettings(data: string) {
  if (isPresentOnOS('@amazon-devices/kepler-file-system', '2.0.0')) {
    return FileSystem.writeFile('/data/settings.json', data);
  }

  return saveSettingsWithLegacyApi(data);
}

The lint recognizes guards in an if branch, a conditional expression, and a logical && expression. Avoid suppressing a finding unless another mechanism guarantees that the API is available. If min and target are both 2.0, OS 2.0 APIs don’t require compatibility guards because the app doesn’t claim support for an older OS version.

Native compatibility lint

For projects with kepler.projectType set to native, vega project doctor also checks C and C++ sources. It reports:

Unguarded TryQueryInterface usage for OmniKit interfaces added after min.
Interfaces removed before min or deprecated by target.

For IDL-based interfaces, the lint recognizes exactly one guard: a runtime null-check of a TryQueryInterface<T>() result. A native OS-version check (for example #if __VEGA_OS_VERSION or VEGA_OS_MIN) isn’t a guard the lint recognizes, even though it might seem equivalent. Use an interface-existence check for an optional newer interface:

auto const camera = component.QueryInterface<ICamera>();

if (auto const camera2 = component.TryQueryInterface<ICamera2>()) {
  camera2->captureHdr();
} else {
  camera->capture();
}

Use QueryInterface<T>() only for an interface guaranteed at min. Use TryQueryInterface<T>() and check for nullptr when the interface might be absent.

Suppress a native finding

To suppress a native finding that you have reviewed, add an // @os-version-ok comment. The native linter accepts it in two positions. These differ from the JavaScript and TypeScript rule, where the comment goes on the line above the import:

At the end of the line of the call. This suppresses that call only.
On its own line directly above the call.

// @os-version-ok
auto const camera2 = component.TryQueryInterface<ICamera2>();

component.TryQueryInterface<ICamera2>(); // @os-version-ok

The comment must contain only the directive, and the directive is case-sensitive. These comments don’t suppress the finding:

A comment placed two lines above the call.
A comment that adds other text, such as // do NOT add @os-version-ok here.
A misspelling, such as @os-version-okay.

OS version module entries in a native project

On a native project (kepler.projectType set to native), vega build writes the OS version module entries into your source manifest.toml. A native build packages the source manifest and has no staging step. A native project is the only project type where these entries appear in your own manifest.toml. When vega build writes the entries:

It replaces them. It deletes each OS version module entry that doesn’t match the current min and target, and then writes the correct entries. A change to min or target doesn’t leave an old entry in the file.
It’s idempotent. If the entries are already correct, the file doesn’t change.
It runs after all the checks that can refuse the build. If vega build refuses to build, your manifest.toml doesn’t change.

Run the compatibility checks

Run:

vega project doctor

Fix errors before building. Warnings identify deprecated APIs or other compatibility risks that don’t currently block the build. Then build and test both ends of the supported range:

To confirm each isPresentOnOS guard evaluates to false and the app takes the fallback branch, test on the min OS version.
To confirm each isPresentOnOS guard evaluates to true and the app takes the OS 2.0 API branch, test on OS 2.0.
Confirm the app installs and starts on both versions.

Find APIs available in OS 2.0

Use the Vega API Reference and the React Native for Vega Reference to identify APIs and library versions available in OS 2.0. Don’t infer availability from a package’s latest npm version. The SDK compatibility manifest and the generated API reference are the authoritative availability sources.

​Choose the OS versions your app supports

​Choose min

​Upgrade an existing app to target OS 2.0

​Migrate from SDK 0.23 or earlier

​Choose min for an app that ran on OS 1.1

​Add the section and re-align your project

​Example manifest before and after

​JavaScript and TypeScript compatibility lint

​Native compatibility lint

​Suppress a native finding

​OS version module entries in a native project

​Run the compatibility checks

​Find APIs available in OS 2.0

​Related topics