NPM private repository configuration

Why a Private NPM Repository is Needed

During internal enterprise development, there is often a need to share private modules. These modules may contain sensitive code or business logic that is not suitable for publication on the public NPM repository. Setting up a private NPM repository can address the following issues:

• Securely store and distribute private packages
• Control package access permissions
• Speed up dependency installation (by caching public packages)
• Centralize management of internal dependency versions

Common Private NPM Repository Solutions

Verdaccio

Verdaccio is a lightweight private NPM proxy registry with the following features:

• Zero configuration required to run
• Supports a plugin system
• Built-in small database
• Supports Docker deployment

Install Verdaccio:

npm install -g verdaccio  

Start the service:

verdaccio  

Nexus Repository

Nexus is a more powerful repository manager that supports multiple package formats:

• Supports NPM, Maven, Docker, and other repository types
• Provides fine-grained access control
• Supports high-availability deployment

GitHub Packages

GitHub's package management service:

• Deep integration with GitHub repositories
• Supports NPM, Maven, RubyGems, etc.
• Free tier has certain limitations

Detailed Verdaccio Configuration

Basic Configuration

Verdaccio's configuration file is typically located at ~/.config/verdaccio/config.yaml. Key configuration items include:

storage: ./storage  
plugins: ./plugins  

web:  
  title: Verdaccio  
  # comment out to disable gravatar support  
  # gravatar: false  

auth:  
  htpasswd:  
    file: ./htpasswd  
    # Maximum amount of users allowed to register, defaults to "+inf".  
    # You can set this to -1 to disable registration.  
    # max_users: 1000  

uplinks:  
  npmjs:  
    url: https://registry.npmjs.org/  

packages:  
  '@*/*':  
    access: $all  
    publish: $authenticated  
    proxy: npmjs  

  '**':  
    access: $all  
    publish: $authenticated  
    proxy: npmjs  

server:  
  keepAliveTimeout: 60  

middlewares:  
  audit:  
    enabled: true  

logs:  
  - {type: stdout, format: pretty, level: http}  

User Authentication

Add a user:

npm adduser --registry http://localhost:4873  

Login:

npm login --registry http://localhost:4873  

Publishing Packages

In the project directory:

npm publish --registry http://localhost:4873  

Client Configuration

Global Use of Private Repository

Set the default npm registry:

npm config set registry http://localhost:4873  

Project-Level Configuration

Create an .npmrc file in the project root directory:

registry=http://localhost:4873  
//localhost:4873/:_authToken="your-auth-token"  

Scoped Packages

For specific scoped packages, configure the registry separately:

npm config set @mycompany:registry http://localhost:4873  

Or in package.json:

{  
  "publishConfig": {  
    "registry": "http://localhost:4873"  
  }  
}  

Advanced Configuration

Plugin System

Example of installing a plugin (e.g., verdaccio-auth-memory):

npm install verdaccio-auth-memory  

Then enable it in the configuration file:

auth:  
  auth-memory:  
    users:  
      admin:  
        password: $2a$10$... # bcrypt-encrypted password  

HTTPS Configuration

Generate a self-signed certificate:

openssl req -newkey rsa:2048 -nodes -keyout key.pem -x509 -days 365 -out cert.pem  

Configure HTTPS:

server:  
  https:  
    key: /path/to/key.pem  
    cert: /path/to/cert.pem  
    ca: /path/to/ca.pem  

Cluster Deployment

Run multiple instances using PM2:

pm2 start verdaccio --name="verdaccio" -i max  

Configure shared storage:

storage: /shared/storage  

Integration with CI/CD

GitHub Actions Example

name: Publish Package  

on:  
  push:  
    branches: [ main ]  

jobs:  
  publish:  
    runs-on: ubuntu-latest  
    steps:  
      - uses: actions/checkout@v2  
      - uses: actions/setup-node@v2  
        with:  
          node-version: '14'  
      - run: npm install  
      - run: npm publish  
        env:  
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}  

Installing Private Dependencies

Install private dependencies in CI:

echo "//registry.npmjs.org/:_authToken=$NPM_TOKEN" > .npmrc  
npm install  

Performance Optimization

Caching Strategy

Configure upstream proxy caching:

uplinks:  
  npmjs:  
    url: https://registry.npmjs.org/  
    cache: true  
    maxage: 30m  
    max_fails: 3  

Storage Optimization

Use external storage:

store:  
  memory:  
    limit: 1000  

Monitoring and Maintenance

Log Analysis

Configure log levels:

logs:  
  - {type: file, path: verdaccio.log, level: info}  
  - {type: stdout, format: pretty, level: http}  

Health Check

Add a health check endpoint:

server:  
  healthCheck:  
    enabled: true  
    interval: 30  

Migrating Existing Packages

Migrating from Public Repository

Download and republish:

npm pack some-package  
tar -xzvf some-package-1.0.0.tgz  
cd package  
npm publish --registry http://localhost:4873  

Batch Migration Tools

Use npm-download and npm-upload tools:

npm install -g npm-download npm-upload  
npm-download --registry https://registry.npmjs.org some-package  
npm-upload --registry http://localhost:4873 some-package-1.0.0.tgz  

Troubleshooting Common Issues

Permission Issues

Example error:

npm ERR! code E403  
npm ERR! 403 403 Forbidden - PUT http://localhost:4873/my-package  

Solutions:

1. Ensure you are logged in
2. Check if the package name is already taken
3. Verify the user has publish permissions

Proxy Issues

Configure proxy:

http_proxy: http://proxy.example.com:8080  
https_proxy: http://proxy.example.com:8080  
no_proxy: localhost,127.0.0.1  

Insufficient Storage Space

Clean up old versions:

verdaccio-storage cleanup --config ~/.config/verdaccio/config.yaml  

Or configure automatic cleanup:

store:  
  cleanup:  
    enabled: true  
    max_versions: 5  
    max_days: 30