How to Host Your Private / Custom npm Packages: A Step-by-Step Guide

When working on a project, especially within a team or organization, there are times when you need to host your own custom npm packages. Whether you’re developing internal libraries or need to manage dependencies privately, hosting your npm package on your own server can be a practical solution. In this article, let’s explore several methods to host your custom npm packages, from simple solutions to more scalable approaches.

Image by vectorjuice on Freepik

Option 1: Hosting .tar.gz Archives (Quick and Simple)

If you’re looking for a quick and straightforward way to host your custom npm package, creating a .tar.gz (or .tgz) archive and storing it on your server is a good option. It’s a great solution if you only have a few packages or need to get up and running quickly.

How It Works:

1. Package Your Module: Inside your module’s directory, run the following command to create a .tar.gz file:

npm pack

This command generates an archive file containing your package’s source code.

2. Upload the Archive: Upload this .tar.gz file to your server. You can use FTP, SCP, or any method you prefer. The file should be publicly accessible via a URL, for example: https://your-server.com/packages/your-package-name.tar.gz

3. Update package.json: In your project’s package.json, reference the URL of the .tar.gz file:

{
  "dependencies": {
    "your-package-name": "https://your-server.com/packages/your-package-name.tar.gz"
  }
}

4. Install the Package: Run npm install in your project directory. npm will fetch the .tar.gz file from your server and install it just like any other package.

Pros:

• It’s fast and easy to set up.
• There’s no need to manage a full registry system.
• Great for small projects or quick solutions.

Cons:

• There’s no automatic versioning, so you’ll need to manually manage versions.
• It’s a bit more difficult to manage if you have many packages or need more features.

This method is perfect if you’re looking for a simple and quick solution to host a small number of packages.

Option 2: Using a Private npm Registry with Verdaccio

If you need more advanced features like version control, access management, and package metadata, setting up a private npm registry with Verdaccio is a fantastic choice. Verdaccio is an open-source, lightweight npm registry that makes it easy to host your own custom packages while still allowing you to proxy public npm packages.

How It Works:

1. Install Verdaccio: On your server, install Verdaccio by running:

npm install -g verdaccio

2. Start the Registry: Run Verdaccio with:

verdaccio

By default, Verdaccio will be available at http://localhost:4873.

3. Publish Your Package: After configuring npm to use Verdaccio as your registry (with npm set registry http://localhost:4873/), you can publish your package to it using:

npm publish

4. Install Packages: To install packages from your private registry, just update your package.json to include the package name, and run npm install.

Pros:

• Automatically handles versioning and package metadata.
• Allows you to set access controls and manage private packages.
• Can proxy public npm packages, reducing the load on your server.

Cons:

• Requires a bit of setup and maintenance.
• You’ll need to manage the Verdaccio server.

Verdaccio is a great option if you need a more robust and scalable solution with full package management.

Option 3: GitHub Packages (Using GitHub as Your Registry)

If your code is already hosted on GitHub, using GitHub Packages is an easy and integrated solution to host npm packages. It works well for both public and private packages, and it integrates seamlessly with your GitHub workflow.

How It Works:

1. Publish to GitHub Packages: Push your npm package to your GitHub repository and configure the project to publish to GitHub Packages.

2. Reference the Package: In your package.json, reference the package using the GitHub URL, for example:

{
  "dependencies": {
    "your-package-name": "github:user/repository#tag"
  }
}

3. Install the Package: If the package is private, you may need to authenticate with your GitHub token, but once configured, you can easily install the package by running npm install.

Pros:

• Easily integrates with your GitHub repositories.
• Free for public packages and integrates with GitHub Actions for CI/CD.
• Handles versioning and package management automatically.

Cons:

• Requires a GitHub account, and you may need a paid plan for private packages.
• More setup compared to the .tar.gz method.

GitHub Packages is a great choice for teams already using GitHub, and it’s a smooth, integrated solution for hosting packages directly within your development workflow.

Option 4: Direct GitHub Repository URL (Git-Based Installation)

If you don’t want to mess with a registry system, you can install npm packages directly from a Git repository. This method uses Git to fetch the package directly without needing a npm registry.

How It Works:

1. Host Your Package on GitHub: Make sure your npm package is stored in a Git repository.

2. Reference the Git Repo: In your package.json, reference the Git repository directly:

{
  "dependencies": {
    "your-package-name": "git+https://github.com/username/your-package-name.git"
  }
}

3. Install the Package: Run npm install to fetch and install the package directly from the Git repository.

Pros:

• No registry setup is required.
• Works well for quick solutions or one-off dependencies.
• Useful for small, personal projects.

Cons:

• Harder to manage versions.
• Less scalable and more difficult to handle if you have many dependencies.

This method is a quick and easy way to share packages without needing a formal registry system.

Option 5: npm Enterprise or Cloud-Based Solutions

For larger teams or enterprise-level projects, services like npm Enterprise, AWS CodeArtifact, or Azure Artifacts provide fully managed, scalable npm registries. These services are ideal for large organizations needing robust security, versioning, and support.

How It Works:

1. Set Up a Private Registry: Use npm Enterprise or a cloud provider to set up a private registry for your npm packages.

2. Publish Your Packages: Publish your custom packages to the registry.

3. Configure Your npm Clients: Set up your npm clients to authenticate with the private registry.

Pros:

• Fully managed and scalable solution.
• Supports access control, security, and permissions.
• Ideal for large teams with complex needs.

Cons:

• Typically requires a paid subscription.
• Overkill for small projects or teams.

Cloud-based registries are a great choice if your team needs a fully managed, enterprise-level solution with scalability and strong security features.

Choosing the right way to host custom npm packages depends on your project size and requirements. For quick and simple solutions, hosting .tar.gz archives on your own server is the easiest approach. If you need more robust features like versioning and access control, setting up a private npm registry with Verdaccio or using GitHub Packages may be the better option. For larger teams and enterprise use cases, services like npm Enterprise or cloud-based registries provide scalable, secure solutions.

Each of these methods offers its own set of advantages and trade-offs, so the best option for you will depend on your specific needs, infrastructure, and scale of the project.