Working with Vercel's private registry
Learn how to set up Vercel's private registry for use locally, in Vercel, and in your CI.Vercel distributes packages with the @vercel-private scope through our
private npm registry, requiring authentication through a Vercel account for
each user.
Access to @vercel-private packages is linked to
access to products. If you have trouble accessing a package, please check that
you have access to the corresponding Vercel product.
If you're the first person on your team to use Vercel's private registry, you'll need to set up your workspace to fetch packages from the private registry.
Execute the following command to configure your package manager to fetch
packages with the @vercel-private scope from the private registry. Note that
you can run this command with any package manager, such as npm, yarn, or
pnpm. If you're using modern Yarn (v2 or newer) see the Using modern versions of Yarn section below.
npm config set --location=project @vercel-private:registry "https://vercel-private-registry.vercel.sh/registry"This command creates an .npmrc file (or updates one if it exists) at the root
of your workspace. We recommend committing this file to your repository, as it
will help other engineers get on board faster.
Yarn version 2 or newer ignores the .npmrc config file so you will need to use this command instead to add the
registry to your project's .yarnrc.yml file:
yarn config set npmScopes.vercel-private.npmRegistryServer "https://vercel-private-registry.vercel.sh/registry"Each team member will need to complete this step. It may be helpful to summarize this step in your team's onboarding documentation.
To log in, use the following command and follow the prompts:
npm login --scope=@vercel-privateThe minimum required version of npm to log into the registry is 8.14.0
During this process, you will be asked to log in to your Vercel account. Ensure that the account that you log in to has access to the Vercel product(s) that you're trying to install.
You should now have a .npmrc file in your home directory that contains the
authentication token for the private registry.
Yarn version 2 or newer requires the authentication token to be saved in a
.yarnrc.yml file. After running the above command, you can copy the token
from the .npmrc file with:
auth_token=$(awk -F'=' '/vercel-private-registry.vercel.sh\/:_authToken/ {print $2}' $(npm config get userconfig)) \
&& yarn config set --home 'npmRegistries["https://vercel-private-registry.vercel.sh/registry"].npmAuthToken' $auth_tokenNote the --home flag, which ensures the token is saved in the global .yarnrc.yml
rather then in your project so that it isn't committed.
Verify your login status by executing:
pnpm whoami --registry=https://vercel-private-registry.vercel.sh/registry
The Yarn command only works with Yarn version 2 or newer, use the npm command if using Yarn v1.
You should see your Vercel username returned if everything is set up correctly.
When a user tries to install a package from the private registry without first logging in, the error message might be unclear. To help, we suggest adding a pre-install message that provides instructions to those unauthenticated users.
Create a preinstall.mjs file with your error message:
import { exec } from 'node:child_process';
import { promisify } from 'node:util';
const execPromise = promisify(exec);
try {
await execPromise(
`npm whoami --registry=https://vercel-private-registry.vercel.sh/registry`,
);
} catch (error) {
throw new Error(
`Please log in to the Vercel private registry to install \`@vercel-private\`-scoped packages:\n\`npm login --scope=@vercel-private\``,
);
}Then add the following script to the scripts field in your package.json:
{
"scripts": {
"pnpm:devPreinstall": "node preinstall.mjs"
}
}Now that your local environment is set up, you can configure Vercel to use the private registry.
- Create a Vercel authentication token on the Tokens page
- To set the newly created token in Vercel, navigate to the Environment Variables settings for your Project
- Add a new environment variable with the name
VERCEL_TOKEN, and set the value to the token you created above. We recommend using a Sensitive Environmental Variable for storing this token - Add a new environment variable with the name
NPM_RC, and set the value to the following:
@vercel-private:registry=https://vercel-private-registry.vercel.sh/registry
//vercel-private-registry.vercel.sh/:_authToken=${VERCEL_TOKEN}If you already have an NPM_RC environment variable, you can append the above
to that existing value.
Vercel should now be able to install packages from the private registry when building your Project.
The instructions below are for GitHub Actions, but configuring other CI providers should be similar:
- Create a Vercel authentication token on the Tokens page. For security reasons, you should use a different token from the one you created for Vercel in the previous step
- Once you have a new token, add it as a secret named
VERCEL_TOKENto your GitHub repository or organization. To learn more about how to add secrets, Using secrets in GitHub Actions - Finally, create a workflow for the product you're setting up. The example workflow below is for Conformance and assumes that you're using pnpm as your package manager.In this example we also pass the token to the Conformance CLI, as the same token can be used for CLI authentication
name: Conformance
on:
pull_request:
branches:
- main
jobs:
conformance:
name: 'Run Conformance'
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v3
- name: Set up Node.js
uses: actions/setup-node@v4
with:
node-version-file: '.node-version'
- name: Set up pnpm
uses: pnpm/action-setup@v3
- name: Set up Vercel private registry
run: npm config set //vercel-private-registry.vercel.sh/:_authToken $VERCEL_TOKEN
env:
VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}
- name: Install dependencies
run: pnpm install
- name: Run Conformance
run: pnpm conformance
env:
VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}By default, GitHub workflows are not required. To require the workflow in your repository, create a branch protection rule on GitHub to Require status checks to pass before merging.
Was this helpful?