Working with Vercel's private registry

Vercel distributes packages with the @vercel-private scope through our private npm registry, requiring authentication through a Vercel account for each user.

1. Set up your workspace

   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.

   Setting registry server using modern versions of Yarn

   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"

2. Log in to the private 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-private

   The 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.

   Setting token using modern versions of Yarn

   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_token

   Note 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.

3. Verify your setup

   Verify your login status by executing:

   pnpm

   yarn

   npm

   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.

4. Optionally set up a pre-install message for missing credentials

   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:

   preinstall.mjs

   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:

   pnpm

   yarn

   npm

   {
     "scripts": {
       "pnpm:devPreinstall": "node preinstall.mjs"
     }
   }

Now that your local environment is set up, you can configure Vercel to use the private registry.

1. Create a Vercel authentication token on the Tokens page
2. To set the newly created token in Vercel, navigate to the Environment Variables settings for your Project
3. 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
4. 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}

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:

1. 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
2. Once you have a new token, add it as a secret named VERCEL_TOKEN to your GitHub repository or organization. To learn more about how to add secrets, Using secrets in GitHub Actions
3. 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.