Private Dependencies

Vercel Agent installs private npm packages using your repository's existing package manager. Add NPM_TOKEN or NPM_RC as a shared team environment variable to authenticate with your registry.

Your package manager runs its usual install command while Vercel Agent authenticates package downloads as registry requests leave the sandbox.

Credential values stay outside the sandbox, so the agent and sandbox processes cannot read them.

Registry authentication only covers package downloads. Publishing and registry administration aren't supported. Keep credentials out of prompts and commands.

Add your credentials in your Vercel team's settings:

1. Open Settings, then select Environment Variables.
2. Add a Shared Environment Variable using the name and value described below.
3. Select Development or Preview, then save the variable.

You don't need to link these variables to individual projects. Vercel Agent checks Development before Preview and ignores Production and project-level variables.

Use NPM_TOKEN for packages hosted on registry.npmjs.org. Set its value to an npm access token with read access to the private packages your repository needs.

Use NPM_RC for a custom registry or multiple registries. Set its value to the registry configuration from your .npmrc file.

For GitHub Packages:

@acme:registry=https://npm.pkg.github.com/
//npm.pkg.github.com/:_authToken=${GITHUB_PACKAGES_TOKEN}

For JFrog Artifactory:

@acme:registry=https://acme.jfrog.io/artifactory/api/npm/npm-local/
//acme.jfrog.io/artifactory/api/npm/npm-local/:_authToken=${ARTIFACTORY_TOKEN}

Replace @acme and the registry URL with your own. Add each referenced token, such as GITHUB_PACKAGES_TOKEN, as a Shared Environment Variable in the same environment as NPM_RC. Each token needs read access to the packages in its registry.

To use multiple registries, add an entry for each package scope and its registry credentials. You can also set registry to choose the default registry.

When both NPM_RC and NPM_TOKEN are set in the same environment, NPM_RC takes precedence.

To give Vercel Agent different credentials from your builds, use VERCEL_AGENT_NPM_RC or VERCEL_AGENT_NPM_TOKEN. Within each environment, Vercel Agent selects the first defined variable in this order:

1. VERCEL_AGENT_NPM_RC
2. VERCEL_AGENT_NPM_TOKEN
3. NPM_RC
4. NPM_TOKEN

To disable registry authentication, set VERCEL_AGENT_NPM_RC to an empty string in Development. This also stops fallback to Preview.

• Registry URLs must use HTTPS with a DNS hostname and no custom port.
• NPM_RC supports token and basic authentication. Client certificates are unsupported.

If a private package fails to install:

• Check that the token has read access to the package.
• Check that registry URLs and package scopes match your dependencies.
• Add any variables referenced by NPM_RC to the same environment as NPM_RC.

If a Development NPM_RC or VERCEL_AGENT_NPM_RC references a missing variable, Vercel Agent retries the same configuration key in Preview. To use that fallback, define the configuration and its referenced variables in Preview.

Empty or malformed configuration stops lookup instead of falling back to a lower-priority variable.