Background:
This article outlines recommended semver expressions to use for Amazon distributed npm libraries (@amzn scoped libraries) for use in your application’s package.json.
Guidance:
@amzn scoped npm libraries should utilize ~ semver expressions for package versioning in your application’s package.json at this time.
We previously communicated the plan to move JS Bundles to the System. 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 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.
As we continue to roll this feature out, 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, the Vega team will provide updated library version guidance.
A table of all @amzn scoped packages can be found at the bottom of this post with the version guidance as of the 15-July 0.20 incremental release.
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. The instructions for npm are listed here and the equivalent instructions for Yarn and pnpm can be found in the FAQ section 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 a1.3your 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 to1.2.3until thepackage.jsonis 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 runnpm updateto reevaluate for new dependencies. However, lock files (likepackage-lock.json) will only be re-evaluated and updated when explicit update commands are run.*- We do not recommend use of*inpackage.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 table uses ~ and ^ to define ranges; however, your are welcome to define ranges using hyphenated or other supported semver syntax. In the future, Amazon may recommend explicit ranges.
This guidance conflicts with <fill in the blank> tech doc in the Vega documents on developer.amazon.com, which is correct?
We are in the process of standardizing semver expression guidance across all @amzn scoped packages across our documentation and you will see all of the documentation in the portal align to this guidance.
What about non-@amzn dependencies? Do I need to follow this guidance for those as well?
No, please continue versioning non-@amzn 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 9.x onwards only
pnpm start --reset-cache
pnpm clean
pnpm update
pnpm list
Recommended Versioning Table
| Library | Recommended Version Expression | System or App Bundled |
|---|---|---|
| @amzn/appium-kepler-driver | ~3.16.0 | App |
| @amzn/aps-client-library | ~0.13.0 | App |
| @amzn/asset-resolver-lib | ~1.0.1767254400 | System |
| @amzn/eslint-plugin-kepler | ~0.1.1 | App |
| @amzn/expo-application | ~2.0.1751782280 | App |
| @amzn/expo-asset | ~2.0.1751782280 | App |
| @amzn/expo-brightness | ~2.0.1722663255 | App |
| @amzn/expo-checkbox | ~2.0.1751782280 | App |
| @amzn/expo-constants | ~2.0.1751782280 | App |
| @amzn/expo-crypto | ~2.0.1751782280 | App |
| @amzn/expo-device | ~2.0.1751782280 | App |
| @amzn/expo-file-system | ~2.0.1751782280 | App |
| @amzn/expo-font | ~2.0.1751782280 | App |
| @amzn/expo-gl | ~2.0.1751782280 | App |
| @amzn/expo-image | ~2.0.1751782280 | App |
| @amzn/expo-image-manipulator | ~2.0.1751782280 | App |
| @amzn/expo-linear-gradient | ~2.0.1751782280 | App |
| @amzn/expo-linking | ~2.0.1751782280 | App |
| @amzn/expo-localization | ~2.0.1751782280 | App |
| @amzn/expo-network | ~2.0.1751782280 | App |
| @amzn/expo-notifications | ~2.0.1751782280 | App |
| @amzn/expo-splash-screen | ~2.0.1751782280 | App |
| @amzn/expo-sqlite | ~2.0.1751782280 | App |
| @amzn/expo-system-ui | ~2.0.1751782280 | App |
| @amzn/headless-task-manager | ~1.2.4 | System |
| @amzn/kepler-adid-retriever | ~1.0.12 | System |
| @amzn/kepler-amazon-device-messaging | ~1.0.10 | App |
| @amzn/kepler-aps-client | ~1.0.5 | System |
| @amzn/kepler-channel | ~1.1.29 | System |
| @amzn/kepler-cli-platform | ~0.20.4 | App |
| @amzn/kepler-content-personalization | ~1.2.6 | System |
| @amzn/keplercrypto | ~2.0.0 | System |
| @amzn/kepler-epg-provider | ~1.9.45 | System |
| @amzn/kepler-epg-sync-scheduler | ~1.2.60 | System |
| @amzn/kepler-file-system | ~0.0.3 | System |
| @amzn/kepler-graphics | ~2.3.1 | System |
| @amzn/kepler-identifiers | ~0.1.1 | System |
| @amzn/kepler-media-account-login | ~1.1.8 | System |
| @amzn/kepler-media-content-launcher | ~2.0.8 | System |
| @amzn/kepler-media-content-metadata | ~1.0.4 | System |
| @amzn/kepler-media-controls | ~1.0.9 | System |
| @amzn/keplermediadescriptor | ~1.1.4 | System |
| @amzn/kepler-media-types | ~1.0.0 | App |
| @amzn/kepler-metrics-api | ~0.7.50 | App |
| @amzn/kepler-module-resolver-preset | ~0.1.2 | App |
| @amzn/kepler-parental-controls | ~1.0.4 | System |
| @amzn/kepler-performance-api | ~0.1.0 | App |
| @amzn/kepler-player-client | ~2.2.1 | System |
| @amzn/kepler-player-server | ~2.2.1 | System |
| @amzn/keplerscript-appstore-iap-lib | ~2.12.10 | System |
| @amzn/keplerscript-appstore-pwa-lib | ~1.3.8 | System |
| @amzn/keplerscript-audio-lib | ~2.0.6 | System |
| @amzn/keplerscript-epg | ~2.7.0 | System |
| @amzn/keplerscript-identity-lwa-lib | ~0.0.46 | System |
| @amzn/keplerscript-kepleri18n-lib | ~1.1.1 | App |
| @amzn/keplerscript-native-ui-components | ~2.7.0 | System |
| @amzn/keplerscript-netmgr-lib | ~2.0.11 | System |
| @amzn/keplerscript-orchid | ~1.0.0 | App |
| @amzn/keplerscript-react-native-reanimated | ~2.0.1751782280 | System |
| @amzn/keplerscript-react-native-safe-area-context | ~3.2.0 | App |
| @amzn/keplerscript-react-navigation-bottom-tabs | ~5.11.10 | App |
| @amzn/keplerscript-react-navigation-compat | ~5.3.15 | App |
| @amzn/keplerscript-react-navigation-core | ~5.15.3 | App |
| @amzn/keplerscript-react-navigation-devtools | ~5.1.22 | App |
| @amzn/keplerscript-react-navigation-drawer | ~5.12.5 | App |
| @amzn/keplerscript-react-navigation-material-bottom-tabs | ~5.3.15 | App |
| @amzn/keplerscript-react-navigation-material-top-tabs | ~5.3.15 | App |
| @amzn/keplerscript-react-navigation-native | ~5.9.4 | App |
| @amzn/keplerscript-react-navigation-routers | ~5.7.2 | App |
| @amzn/keplerscript-react-navigation-stack | ~5.14.4 | App |
| @amzn/keplerscript-rms-lib | ~1.0.1 | App |
| @amzn/keplerscript-turbomodule-api | ~1.2.4 | App |
| @amzn/kepler-subscription-entitlement | ~1.1.2 | System |
| @amzn/kepler-telemetry-service-config | ~0.1.14 | App |
| @amzn/kepler-telemetry-service-typescript-client | ~0.1.31 | App |
| @amzn/kepler-tools-misc-utils | ~1.1.0 | App |
| @amzn/kepler-ui-components | ~2.2.0 | App |
| @amzn/lottie-react-native | ~2.0.1751782280 | System |
| @amzn/react-linear-gradient | ~2.0.1751782280 | System |
| @amzn/react-native-async-storage__async-storage | ~2.0.1751782280 | System |
| @amzn/react-native-cookies__cookies | ~1.0.1751782280 | System |
| @amzn/react-native-device-info | ~2.0.1751782280 | System |
| @amzn/react-native-fast-image | ~3.0.1 | App |
| @amzn/react-native-gesture-handler | ~2.0.1751782280 | System |
| @amzn/react-native-kepler | ~2.0.1751782280 | System |
| @amzn/react-native-localize | ~2.0.1751782280 | System |
| @amzn/react-native-masked-view__masked-view | ~2.0.1751782280 | System |
| @amzn/react-native-mmkv | ~1.0.2 | App |
| @amzn/react-native-qrcode-svg | ~2.0.1751782280 | App |
| @amzn/react-native-reanimated | ~2.0.1751782280 | System |
| @amzn/react-native-safe-area-context | ~2.0.1751782280 | System |
| @amzn/react-native-screens | ~2.0.1751782280 | System |
| @amzn/react-native-svg | ~2.0.1751782280 | System |
| @amzn/react-native-vector-icons | ~2.0.1751782280 | System |
| @amzn/react-native-w3cmedia | ~2.1.80 | System |
| @amzn/react-navigation__bottom-tabs | ~7.0.1751782280 | System |
| @amzn/react-navigation__core | ~7.0.1751782280 | System |
| @amzn/react-navigation__devtools | ~7.0.1751782280 | System |
| @amzn/react-navigation__drawer | ~7.0.1751782280 | System |
| @amzn/react-navigation__elements | ~7.0.1751782280 | System |
| @amzn/react-navigation__material-bottom-tabs | ~7.0.1751782280 | System |
| @amzn/react-navigation__material-top-tabs | ~7.0.1751782280 | System |
| @amzn/react-navigation__native | ~7.0.1751782280 | System |
| @amzn/react-navigation__native-stack | ~7.0.1751782280 | System |
| @amzn/react-navigation__react-native-tab-view | ~7.0.1751782280 | System |
| @amzn/react-navigation__routers | ~7.0.1751782280 | System |
| @amzn/react-navigation__stack | ~7.0.1751782280 | System |
| @amzn/recommendation-manager | ~2.0.2 | System |
| @amzn/security-manager-lib | ~1.0.1767254400 | System |
| @amzn/sentry__react-native | ~1.0.10 | App |
| @amzn/shopify__flash-list | ~2.0.1751782280 | System |
| @amzn/shopify__react-native-performance | ~2.0.1751782280 | System |
| @amzn/shopify__react-native-performance-lists-profiler | ~1.1.1751782280 | System |
| @amzn/shopify__react-native-performance-navigation | ~3.0.1751782280 | App |
| @amzn/shopify__react-native-performance-navigation-bottom-tabs | ~3.0.1751782280 | App |
| @amzn/shopify__react-native-performance-navigation-drawer | ~3.0.1751782280 | App |
| @amzn/simplesignin | ~1.1.3 | App |
| @amzn/tve-adobe-sso-enabler | ~0.0.4 | App |
| @amzn/types__react-native | ~0.66.15 | App |