How do I use private dependencies with Vercel?

Information on how to use private dependencies with a Vercel deployment.
Last updated on June 4, 2024
Build, Deployment & Git

The Vercel platform allows you to install private dependencies in your project by assigning public or private repositories formatted as npm packages in your package.json file dependencies.

Adding the NPM_TOKEN environment variable to your project allows Vercel to create a .npmrc file to install your private npm packages.

Setting the NPM_TOKEN environment variable on your project on Vercel.
Setting the NPM_TOKEN environment variable on your project on Vercel.

You can also reference public or private repositories formatted as npm packages in your package.json file dependencies. Private repository modules require a special link syntax that varies according to the Git provider.

For GitHub, create a GitHub personal access token with read-only access, and include it in the package URL as follows:

"package-name": "git+https://<username>:<github_token>@github.com/<user>/<repo>.git"

For GitHub Enterprise Server, create a GitHub personal access token with read-only access, and include it in the package URL as follows:

"package-name": "git+https://<username>:<github_token>@<self-hosted-instance.url>/<user>/<repo>.git"

For GitLab, create a GitLab deploy token with read_repository access, and include it in the package URL as follows:

"package-name": "git+https://<token-username>:<token>@gitlab.com/<user>/<repo>.git"

For GitLab self-managed, create a GitLab deploy token with read_repository access, and include it in the package URL as follows:

"package-name": "git+https://<token-username>:<token>@<self-hosted-instance.url>/<user>/<repo>.git"

For Bitbucket, create a Bitbucket app password with read-only access, and include it in the package URL as follows:

"package-name": "git+https://<user>:<app-password>@bitbucket.org/<user>/<repo>.git"

To use private packages from registries other than npm such as Github, add the contents of your .npmrc file as an Environment Variable to your project from the Vercel dashboard. This can be found by selecting the project, and viewing the general tab under the project settings.

Select the desired Environments and add the key NPM_RC with the contents of your .npmrc file as the Value. If your .npmrc contains multiple lines we recommend using Vercel CLI to ensure line breaks are preserved:

vc env add NPM_RC [environment] < /path/to/.npmrc

Note that when NPM_RC and NPM_TOKEN are both present, NPM_RC will take precedence.

Furthermore, Vercel Runtimes are installed from the canonical npm registry so registry.npmjs.org must be one of the lines in your .npmrc file:

registry=https://registry.npmjs.org
@NAMESPACE:registry=https://npm.pkg.github.com/PACKAGENAME
//registry.npmjs.org/:_authToken=TOKEN_FOR_NPM
//npm.pkg.github.com/PACKAGENAME/:_authToken=TOKEN_FOR_GITHUB
Example of an .npmrc file.

At build time, Vercel will dynamically create a .npmrc file and then install your dependencies from package.json.

This allows you access to private packages without having to commit your own .npmrc file to source control.

Couldn't find the guide you need?