connect to private NPM registry

private-npmrc.md

Package Installation Guide

This guide explains how to set up your local environment to install packages from our GitHub Package Registry.

Generate GitHub Personal Access Token (Classic)

1. Go to GitHub Settings:

   • Click your profile photo in the top right
   • Select "Settings"
   • Scroll down to "Developer settings" (bottom left)
   • Click "Personal access tokens" → "Tokens (classic)"
   • Click "Generate new token" → "Generate new token (classic)"

2. Configure token permissions:

   • Give your token a descriptive name (e.g., "npm-packages")
   • Set expiration as needed
   • Select the following scopes:
     • read:packages (to download packages)
     • write:packages (if you need to publish packages)

3. Click "Generate token"

   • IMPORTANT: Copy the token immediately. You won't be able to see it again!

Configure Local Environment

Option 1: Global Configuration

Create or edit the global .npmrc file in your home directory:

# Linux/MacOS: ~/.npmrc

//npm.pkg.github.com/:_authToken=YOUR_TOKEN_HERE
@ORGANIZATION:registry=https://npm.pkg.github.com

Option 2: Project-specific Configuration

Create .npmrc in your project root:

//npm.pkg.github.com/:_authToken=YOUR_TOKEN_HERE
@ORGANIZATION:registry=https://npm.pkg.github.com

Option 3: Environment Variable

Set the auth token as an environment variable:

# Linux/MacOS
export NPM_AUTH_TOKEN=YOUR_TOKEN_HERE

Then in your .npmrc:

//npm.pkg.github.com/:_authToken=${NPM_AUTH_TOKEN}
@ORGANIZATION:registry=https://npm.pkg.github.com

Installing Packages

Once configured, you can install packages using npm/yarn/pnpm:

# Using npm
npm install @ORGANIZATION/package-name

# Using yarn
yarn add @ORGANIZATION/package-name

# Using pnpm
pnpm add @ORGANIZATION/package-name

Troubleshooting

1. 401 Unauthorized

   • Verify your token has the correct permissions
   • Check if the token is correctly pasted in .npmrc
   • Ensure there are no extra spaces in the token

2. 404 Not Found

   • Verify the package name including scope (@ORGANIZATION)
   • Check if you have access to the repository
   • Ensure the package exists in the GitHub Package Registry

3. Package not found

   • Make sure the scope in .npmrc matches the package scope
   • Check if the package is published to the correct registry

Security Notes

• Never commit your .npmrc file containing the auth token
• Add .npmrc to your .gitignore if it contains sensitive information
• Consider using environment variables for tokens in CI/CD environments
• Regularly rotate your personal access tokens