Manage Packages and Dependencies

Your app's dependencies fall into two groups, and Vega manages them differently. This guide explains which tool resolves and installs each kind of dependency, and how your OS version target selects package versions.

OS-provided Vega packages carry the @amazon-devices/ prefix, such as @amazon-devices/kepler-camera. Your [os.version] target constrains which versions of these packages your app can use, and vega project install resolves them for you. Ordinary npm packages, such as react and lodash, resolve the way they always do, through your package manager.

Your package manager installs both kinds. vega project never runs it for you. Instead, vega project resolves the correct versions of the OS-provided packages for your OS version target and writes them into package.json. You then run your own package manager, such as npm, yarn, or pnpm, to download and install them.

The resolve, install, and build chain

Before you start, confirm that your manifest.toml has an [os.version] section. vega project install --fix resolves your OS target from that section, so on a project without one it fails with Missing OS Version and writes nothing. To create the section and re-align in a single command, add both flags: vega project install --fix --os-min 1.2 --os-version 1.2. For the other ways to add the section, see Manifest [os.version] Section.

To take a project from resolved versions to a built app, run the following commands.

vega project install --fix
npm install
vega project doctor
npx react-native build-vega

1. vega project install --fix picks the newest published version of each @amazon-devices/* dependency that's compatible with your [os.version].target, then writes those versions into package.json. It doesn't download anything or change the node_modules folder.

2. npm install downloads and installs the versions that vega project install wrote. Use whichever package manager your project already uses.

3. vega project doctor validates your project before you build. It exits non-zero on failure, so you can use it as a gate in a CI pipeline.

4. npx react-native build-vega builds your app and produces the vpkg. You can also use the build script in your package.json.

For full command and option details, see Vega SDK CLI Reference.

How the OS version target selects package versions

The [os.version] section in your manifest.toml drives which versions vega project install resolves.

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

• target - vega project install resolves each @amazon-devices/* package to the newest version available for this OS version.

• min - The oldest OS version your app supports. The tooling records any OS-provided module available at min as a required [[needs.module]] entry. It records modules that first appear after min and up to target as optional [[wants.module]] entries. Your code must guard the APIs those modules add so that your app still runs on devices at min.

Both min and target must be quoted "M.n" strings that name officially minted OS versions. Vega rejects a value that isn't minted, even when the value is numerically well-formed. As of Vega SDK 0.24, OS 1.2 is the only minted OS version, so set both min and target to 1.2.

For the full field definitions, validation rules, and the module ID format, see Manifest [os.version] Section.

Add, update, and re-align packages

The following table describes the command for each action.

After any command that rewrites package.json, which includes install and update, run your package manager to install the changes, then rebuild.

update-manifest works differently. It rewrites the [[needs.module]] and [[wants.module]] entries in manifest.toml rather than package.json. After you run it, run vega project install --fix to re-align package.json to the new module entries, then run your package manager, then rebuild.

Choose your package manager

vega project commands write package.json only. They never invoke npm, yarn, or pnpm. Use whichever package manager your project already uses. The resolved @amazon-devices/* versions are plain package.json entries, and any npm-compatible package manager installs them the same way.

Related topics

• Target OS Versions
• Manifest [os.version] Section
• Vega SDK CLI Reference
• Validate App Manifest in Vega Studio

Last updated: Aug 21, 2026