Below is an in-depth guide on how to set up a private npm repository, including various alternatives and practical code snippets to help you get started. Whether you’re a solo developer or part of a large team, hosting your own npm packages privately can give you control, flexibility, and improved security.

Why Use a Private npm Repository?

1. Security and Control: Keep your packages and code internal.
2. Faster Builds: Reduce external dependencies and network latency.
3. Access Management: Control who can access or publish certain packages.
4. Versioning and Archiving: Maintain multiple versions of internal packages without confusion or external disruptions.

Common Approaches to Hosting a Private npm Repository

1. Self-Hosted Solutions

   • Verdaccio: A popular open-source lightweight npm proxy registry.
   • Sonatype Nexus: A comprehensive platform for hosting multiple repository formats (npm, Maven, etc.).
   • JFrog Artifactory: A widely used binary repository manager.

2. Managed by Git Hosts

   • GitHub Packages: Host private npm packages within your GitHub organization.
   • GitLab Packages: Provides a built-in npm registry as part of GitLab’s DevOps platform.
   • Bitbucket (via third-party integrations or custom solutions).

3. npm Enterprise

   • If you have large teams and want enterprise-level features (advanced access control, security audits, etc.), npm Enterprise might be an option.

1. Setting Up a Private npm Registry with Verdaccio

Verdaccio is an open-source npm registry proxy that’s easy to set up and use. It allows you to host private packages and also cache public packages from the official npm registry.

1.1 Install Verdaccio

Assuming Node.js is already installed on your machine:

# Install Verdaccio globally
npm install --global verdaccio

1.2 Start Verdaccio

verdaccio

By default, Verdaccio starts on port 4873. You can open your browser to http://localhost:4873 to see the Verdaccio UI.

1.3 Configure Verdaccio

Verdaccio creates a default config file on first run. You can customize it by editing it (the file path may vary depending on your system). A typical config (~/.config/verdaccio/config.yaml) looks like:

storage: ./storage
auth:
  htpasswd:
    file: ./htpasswd
    max_users: 100

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

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

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

middlewares:
  audit:
    enabled: true

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

• storage: Directory where Verdaccio stores packages.
• uplinks: Points to the official npm registry.
• packages: Defines rules for access, publishing, and proxy.

1.4 Create a User and Log In

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

This prompts for username, password, and email. Once done, you’ll be logged in to your private registry.

1.5 Publish a Package

In a package directory with a valid package.json:

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

That’s it! Your package is now published to your local Verdaccio registry.

1.6 Install from Your Private Registry

To install a package from this registry, you can either:

• Use the --registry flag:

  npm install <package-name> --registry http://localhost:4873

• Or set your .npmrc to point to this registry globally or in a specific project:

  registry=http://localhost:4873

2. Using GitHub Packages

If you already host your code on GitHub, using GitHub Packages can be a convenient way to keep everything under one roof.

2.1 Enable GitHub Packages for Your Repository

1. Go to your repository on GitHub.
2. Click on Settings -> Packages.
3. Make sure GitHub Packages is enabled for your organization/account.

2.2 Authenticate to GitHub Packages

Create a Personal Access Token (PAT) with the read:packages and write:packages scopes. You can generate this token from your GitHub settings under Developer settings -> Personal access tokens.

Add your token to .npmrc:

//npm.pkg.github.com/:_authToken=YOUR_PERSONAL_ACCESS_TOKEN
@YOUR_GITHUB_USERNAME:registry=https://npm.pkg.github.com

Replace YOUR_GITHUB_USERNAME with your actual username or GitHub organization name.

2.3 Publish a Package to GitHub Packages

Update your package.json with a scope matching your GitHub username or organization:

{
  "name": "@YOUR_GITHUB_USERNAME/my-private-package",
  "version": "1.0.0",
  "publishConfig": {
    "registry": "https://npm.pkg.github.com"
  }
}

Then publish:

npm publish

2.4 Install from GitHub Packages

Make sure .npmrc is pointing to GitHub Packages, then:

npm install @YOUR_GITHUB_USERNAME/my-private-package

3. Using GitLab Packages

GitLab also provides a built-in package registry.

3.1 Set Up GitLab Package Registry

1. Navigate to your GitLab project.
2. Go to Settings -> Packages & Registries -> Package Registry.

3.2 Configure .npmrc

Create or update your local/global .npmrc file with your GitLab credentials:

# For a self-managed GitLab instance, replace gitlab.com with your instance domain
@YOUR_GITLAB_GROUP:registry=https://gitlab.com/api/v4/packages/npm/
//gitlab.com/api/v4/packages/npm/:_authToken=YOUR_GITLAB_PERSONAL_ACCESS_TOKEN

3.3 Publish to GitLab

Update your package.json scope to match the GitLab group or user namespace:

{
  "name": "@YOUR_GITLAB_GROUP/my-private-package",
  "version": "1.0.0",
  "publishConfig": {
    "registry": "https://gitlab.com/api/v4/packages/npm/"
  }
}

Then publish:

npm publish

3.4 Install from GitLab Packages

npm install @YOUR_GITLAB_GROUP/my-private-package

4. Self-Hosted with Sonatype Nexus or JFrog Artifactory

If you’re looking for a robust, on-premise solution that supports multiple repository types, Sonatype Nexus or JFrog Artifactory might be your best bet.

4.1 Nexus Repository

1. Install Nexus Repository Manager on your server or development machine.
2. Log in to the Nexus UI at http://your-nexus-server:8081.
3. Create a new npm (hosted) repository from the Repositories settings.
4. Configure Authentication (if needed) and note the URL.

Use a similar .npmrc setup to point your npm client to your new Nexus npm repository:

registry=http://your-nexus-server:8081/repository/your-npm-hosted/

Publish your package as normal:

npm publish

4.2 JFrog Artifactory

1. Install and launch Artifactory.
2. In the Artifactory UI, create a Local Repository for npm.
3. Configure .npmrc similarly:

registry=http://your-artifactory-server:8081/artifactory/api/npm/your-npm-repo/

Publish using:

npm publish

5. npm Enterprise

For large organizations needing full control, auditing, and advanced security, npm Enterprise is an option. It provides:

• Single Sign-On (SSO) integration.
• Enhanced security scans and auditing.
• Fine-grained access control.

Consult npm Enterprise documentation for setup instructions.

Best Practices and Tips

1. Use Scopes: Scoping your private packages (@company/your-package) helps differentiate them from public packages.
2. .npmrc Management:
   • Use per-project .npmrc files to avoid confusion.
   • Keep credentials out of version control.
3. Automate with CI/CD: Integrate publishing steps into your CI/CD pipelines for consistency.
4. Set up Proxy: Most self-hosted registries can proxy the public npm registry, so you won’t have to switch between registries to install common dependencies.
5. Monitor and Audit: Keep track of downloads, versions, and activity in your registry.

Conclusion

Setting up a private npm repository gives you the freedom to manage and host your own packages securely. Whether you’re using a self-hosted solution like Verdaccio, leveraging managed solutions like GitHub Packages or GitLab Packages, or opting for enterprise solutions like Nexus, Artifactory, or npm Enterprise—the fundamentals remain the same:

1. Configure the registry.
2. Set up authentication.
3. Publish and consume your packages.

Choose the approach that best fits your organization’s requirements around security, scalability, and maintenance. With the examples and code snippets above, you should have a solid foundation to get started hosting your own private npm packages. Happy coding!