Recommended Semver Expressions for Amazon-Distributed Vega Libraries

Vega Open Beta Knowledge Base
1

This article outlines recommended semver expressions to use for Amazon distributed npm libraries (@amazon-devices scoped libraries) for use in your application’s package.json.

Guidance:

@amazon-devices scoped npm libraries should utilize ~ semver expressions for package versioning in your application’s package.json at this time.

Implementations of APIs provided by system JS bundles are contained in the OS and not in the application. In this model, new minor versions of a System JS module can introduce new APIs that are not available on previous versions of the operating system. Updating to a new minor version of an npm package will update the OS version requirement in your application’s manifest during the build process, even if you do not use APIs introduced in that minor version. When you attempt to install an application on an OS version that doesn’t support your application manifest’s API version requirement, the installation will fail.

Pinning to specific minor versions until advised otherwise will ensure that an npm package update does not unnecessarily restrict your ability to target previous versions of the operating system. Additionally, for libraries already System Bundled, your application will automatically receive updated patch versions without app rebuild through OS updates.

With each release update, we will provide updated library version guidance in the Vega API Reference docs:

Release over Release updates:

After each OS and npm update, please double check the release notes for relevant library updates. A master list of the current npm module versions can be found here. At this time, we recommend using ~ based semver expressions for each package you consume. We recommend that after each release, you double check the API list for new major or minor versions and update your package.json file accordingly. Patch versions can be adopted by standard package manager updates. See the npm commands below:

npm start -- --reset-cache // clears metro cache
npm run clean // this assumes that you have a "clean" script in your package.json
npm update // pulls the latest version of your app's dependencies
npm list

FAQs

What happens if I don’t follow this guidance for System Bundled libraries? What risks do I carry?
It depends on what your package.json defines. Examples of potential risks assuming our guidance for a particular package is ~1.2.3

  • ^1.2 - This means that if in the future we release a 1.3 your application will reference that version from the OS immediately. Typically Amazon would increase the minor version when adding new functionality and/or APIs, so the application developer would want to test (and potentially make app changes to use the new API)
  • 1.2.3 - This means that the application will be pinned to 1.2.3 until the package.json is changed. This means that you may miss out on bug fixes by Amazon and/or rely on deprecated versions.
  • ~1.2.0 - While this is theoretically OK so long as you have run npm update to reevaluate for new dependencies. However, lock files (like package-lock.json ) will only be re-evaluated and updated when explicit update commands are run.
  • * - We do not recommend use of * in package.json

What happens if a System Bundled library is defined in my package.json does not match what the OS expects?
The application will fail to install with a Module Not Found error.

Can package.json define explicit ranges?
Yes, for simplicity the examples above use ~ and ^ to define ranges; however, you are welcome to define ranges using hyphenated or other supported semver syntax. In the future, Amazon may recommend explicit ranges.

What about non-@amazon-devices dependencies? Do I need to follow this guidance for those as well?
No, please continue versioning non-@amazon-devices dependencies as you would for any other React Native project.

How do I ensure my package updates are included in my build if I use Yarn or PNPM?
For Yarn

yarn cache clean --all
yarn start -- --reset-cache
yarn clean
yarn upgrade
yarn list

For PNPM

pnpm cache delete # command available from pnpm 9.x onwards only
pnpm start -- --reset-cache
pnpm clean
pnpm update
pnpm list

Last updated: Mar 10, 2026

How to address System Bundles and Troubleshooting