[os.version] section to it, start with Upgrade an existing app. If your app supports a range of OS versions, see Guard newer APIs with isPresentOnOS to learn how to adopt newer APIs safely.
To find the APIs a specific OS version provides, see the Vega API Reference. To find supported third-party library versions, see Supported Libraries and Services.
OS version compared to SDK version
The OS version and the SDK version are two different things, as described in the following table.
The rest of this page covers the OS version.
OS versions and the React Native runtime
Each OS version ships one or more React Native runtimes, and your app runs on exactly one of them. You don’t set the runtime explicitly. The Vega CLI reads it from the@amazon-devices/react-native-* dependency versions in your package.json, so whatever your project already depends on determines the runtime.
The CLI echoes the runtime it resolved in its output, for example 📦 Installed packages for OS Version 1.2 + RN 0.72. To preview a different runtime, pass --rn-version to vega project install, but the normal path is to let the CLI read package.json.
OS 1.2 provides two React Native runtimes, as described in the following table.
Because RN 0.83 arrived at OS 1.2, an app built on the 0.83 runtime can’t set
min below 1.2. No earlier OS version carries the 0.83 runtime. When your min is lower than the OS version your runtime needs, vega project doctor and the build report an error that tells you to raise min. Neither one changes the value for you.
You don’t guard for the React Native runtime at runtime, because your app is built against exactly one runtime and always runs on it. The build tooling keeps this consistent and won’t let you depend on an @amazon-devices/* package version that’s incompatible with your project’s runtime. Runtime guarding with isPresentOnOS applies to library APIs added in an OS version newer than your min, not to runtime differences.
The [os.version] manifest section
To declare the OS version range your app supports, add an[os.version] section to your manifest.toml.
-
min- The oldest OS version your app supports. Your app installs on any device at this version or newer, and you can use the APIs available atminfreely. -
target- The newest OS version your app is built against. You get the APIs up to this version, but you must guard anything added afterminso that your app still works on older devices.
[os.version] section is required to build. Building with npx react-native build-vega fails when the section is missing. Add it by hand, or let the tooling add it with vega project update-manifest --os-min 1.2 --os-version 1.2. For all three authoring paths and the flags each one needs, see Manifest [os.version] Section.
The tooling records your app’s OS-provided modules in the manifest as needs when they’re available at min, and as wants when they arrived between min and target. You don’t write these entries. The build generates them each time you build. For a complete example manifest, see Manifest [os.version] Section. For more information about the entries themselves, see Manifest [needs] Section and Manifest [wants] Section.
Set up compatibility for your app
To set up OS version compatibility, run the following commands from your project root.-
vega project install --fixresolves OS-version-compatible versions of your@amazon-devices/*dependencies intopackage.json. -
npm installinstalls the resolved versions. Use whichever package manager your project already uses. -
vega project doctorvalidates your project before you build. -
npx react-native build-vegabuilds your app and produces thevpkg. You can also use the build script defined in yourpackage.json.
vega project commands never run npm, yarn, or pnpm for you, so run your own package manager after any command that changes package.json.
doctor confirms that your OS versions are valid and that min is less than or equal to target. It also confirms that your package versions match, that required modules are available at min, and that your code guards newer APIs. It exits non-zero on failure, so you can use it in a CI pipeline. For the full option list, see vega project doctor.
Beyond this setup chain, the remaining vega project commands handle narrower tasks. To add a single new @amazon-devices/* package, run vega project install <package> and use your package manager to install it. To preview a change to a different OS target before you apply it, run vega project update --os-version <v> --dry-run. For every command and option, see the Vega SDK CLI Reference.
Upgrade an existing app
To add OS version compatibility to a working app, you don’t have to rewrite anything.-
Add an
[os.version]section to yourmanifest.toml, either by hand or withvega project update-manifest --os-min 1.2 --os-version 1.2. -
Run
vega project install --fixto re-align your@amazon-devices/*dependencies to the OS target. -
Run
npm install, then runvega project doctorto confirm that your project is compatible. - Build your app as usual.
vega project install --fix --os-min 1.2 --os-version 1.2. This form needs both flags. Without --os-version, it can’t resolve a target for a project that has no [os.version] section, and it fails without writing anything.
Your existing code keeps working. If you support a range of OS versions, guard only the newer APIs you choose to adopt.
Guard newer APIs with isPresentOnOS
When your app supports a range of OS versions, meaningmin is older than target, a library version that introduces a newer API might not be present on an older device. An unguarded call to that API crashes on those devices.
To guard the call, use isPresentOnOS, which reports whether a library is present on the running device’s OS at a given version or newer.
isPresentOnOS(libraryName, version) takes the following arguments:
-
libraryName- The npm library name, for example'@amazon-devices/react-native-gesture-handler'. -
version- A semver version string, for example'2.2.0'. The function returnstruewhen the running device’s OS provides that library at the given version or newer.
isPresentOnOS comes from @amazon-devices/kepler-compatibility. To avoid repeated checks, cache the result in a useMemo hook rather than calling it on every render. For more information about the compatibility library, see Enable Backward Compatibility.
Both vega project doctor and the Vega ESLint plugin flag a newer API used without a guard. To suppress the check for one import, add an // @os-version-ok comment on the preceding line.
Test across OS versions
Before you submit your app, install device simulators at both yourmin and target OS versions, then verify that your app installs and runs on each one. Pay attention to your guarded code paths and their fallbacks.
