Set Up and Use Private npm Registries

Advanced18 min

Configure and publish to private npm registries using Verdaccio, GitHub Packages, or npm Teams for internal package distribution.

Prerequisites

-Node.js and npm installed
-Docker installed (for Verdaccio option)
-npm account or GitHub account

Steps

Run a local Verdaccio registry

Start a self-hosted npm registry for development and testing.

$ docker run -d --name verdaccio -p 4873:4873 verdaccio/verdaccio

Verdaccio proxies the public npm registry by default, so you can install public packages through it while hosting private ones.

Configure npm to use the private registry

Set the registry URL for a specific scope.

$ npm config set @myorg:registry http://localhost:4873/

Scope-based registry config lets you use a private registry for @myorg/* packages while everything else goes to the public registry.

Authenticate with the private registry

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

Publish to the private registry

Push a package to your private registry.

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

Configure .npmrc for the project

Create a project-level .npmrc to share registry config with the team.

$ echo '@myorg:registry=http://localhost:4873/' > .npmrc && echo '//localhost:4873/:_authToken=${NPM_TOKEN}' >> .npmrc

Never commit auth tokens to .npmrc. Use environment variables and add .npmrc to .gitignore if it contains secrets. Use a .npmrc template checked into git with token placeholders.

Configure GitHub Packages as an alternative

Use GitHub Packages as a private registry for your organization.

$ npm config set @myorg:registry https://npm.pkg.github.com && npm login --registry https://npm.pkg.github.com --scope=@myorg

Full Script

full-script.sh

#!/bin/bash
# Private npm Registry Setup with Verdaccio
set -euo pipefail

REGISTRY_PORT=${1:-4873}
SCOPE=${2:-"@myorg"}

echo "=== Starting Verdaccio ==="
docker run -d \
  --name verdaccio \
  -p "$REGISTRY_PORT:4873" \
  -v verdaccio-storage:/verdaccio/storage \
  -v verdaccio-conf:/verdaccio/conf \
  verdaccio/verdaccio

echo "Waiting for Verdaccio to start..."
sleep 3

REGISTRY_URL="http://localhost:$REGISTRY_PORT"

echo ""
echo "=== Configuring npm ==="
npm config set "$SCOPE:registry" "$REGISTRY_URL/"

echo ""
echo "=== Registry Status ==="
curl -s "$REGISTRY_URL/-/ping" && echo " Registry is healthy" || echo "Registry is not responding"

echo ""
echo "=== Project .npmrc Template ==="
cat << NPMRC
# Add to .npmrc (do NOT commit tokens)
$SCOPE:registry=$REGISTRY_URL/
//localhost:$REGISTRY_PORT/:_authToken=\${NPM_TOKEN}
NPMRC

echo ""
echo "=== Next Steps ==="
echo "1. Login:   npm login --registry $REGISTRY_URL"
echo "2. Publish: npm publish --registry $REGISTRY_URL"
echo "3. Install: npm install $SCOPE/mypackage"
echo "4. Web UI:  open $REGISTRY_URL"

FAQ

Discussion

Loading comments...

#!/bin/bash # Private npm Registry Setup with Verdaccio set -euo pipefail REGISTRY_PORT=${1:-4873} SCOPE=${2:-"@myorg"} echo "=== Starting Verdaccio ===" docker run -d \ --name verdaccio \ -p "$REGISTRY_PORT:4873" \ -v verdaccio-storage:/verdaccio/storage \ -v verdaccio-conf:/verdaccio/conf \ verdaccio/verdaccio echo "Waiting for Verdaccio to start..." sleep 3 REGISTRY_URL="http://localhost:$REGISTRY_PORT" echo "" echo "=== Configuring npm ===" npm config set "$SCOPE:registry" "$REGISTRY_URL/" echo "" echo "=== Registry Status ===" curl -s "$REGISTRY_URL/-/ping" && echo " Registry is healthy" || echo "Registry is not responding" echo "" echo "=== Project .npmrc Template ===" cat << NPMRC # Add to .npmrc (do NOT commit tokens) $SCOPE:registry=$REGISTRY_URL/ //localhost:$REGISTRY_PORT/:_authToken=\${NPM_TOKEN} NPMRC echo "" echo "=== Next Steps ===" echo "1. Login: npm login --registry $REGISTRY_URL" echo "2. Publish: npm publish --registry $REGISTRY_URL" echo "3. Install: npm install $SCOPE/mypackage" echo "4. Web UI: open $REGISTRY_URL"