Configure your NPM client to use Varnish Orca

To accelerate, control and secure access to your NPM package registries with Varnish Orca, you need to configure your NPM client and override the registry configuration setting.

This tutorial describes 3 ways to configure npm to fetch NPM packages from a Varnish Orca virtual registry, instead of the standard https://registry.npmjs.org/ registry:

1. Run the npm config set registry command to perform a global registry override in your .npmrc file.
2. Manually add a custom registry setting to your .npmrc file.
3. Use the --registry option when installing packages with npm install.

Prerequisites#

Before following the instructions in this tutorial, there are a couple of prerequisites:

• NPM is installed on your machine,
• You have installed and deployed Varnish Orca.
• NPM is configured in your virtual registry configuration in Orca

Here’s an example configuration for Orca that creates a virtual registry configuration named npm that proxies NPM requests to https://registry.npmjs.org:

virtual_registry:
  registries:
  - name: npm
    remotes:
    - url: https://registry.npmjs.org

This configuration allows the npm virtual registry to be matched through the hypothetical hostname https://npm.example.com and caches requested packages.

Option 1: use npm config set registry#

The npm config set command allows you to set configuration parameters in your .npmrc file. We’ll use it to set the registry configuration parameter and point it at the NPM endpoint of our Varnish Orca setup.

We’ll use the hypothetical https://npm.example.com endpoint and run the following command to set it

npm config set registry https://npm.example.com

You can now install packages using npm install and expect the requests to be handled by Varnish Orca.

Option 2: manually edit your .npmrc file#

You can also manually add the registry configuration parameter to your .npmrc file. Make sure the following line is added, assuming we use https://npm.example.com as the hypothetical endpoint for NPM packages in your Varnish Orca deployment:

registry=https://npm.example.com

You can also run the following command to add the registry configuration parameter to .npmrc, or overwrite the value of the registry parameter if it already exists in the configuration file:

grep -q '^registry=' .npmrc && \
sed -i '' 's|^registry=.*|registry=https://npm.example.com|' .npmrc || \
echo 'registry=https://npm.example.com' >> .npmrc

Option 3: set the --registry option when running npm install#

Adding he registry configuration parameter to .npmrc overrides the NPM configuration on a global level, affecting NPM installs for various projects.

There is also a possibility to use a custom registry at request time. The --registry command line option allows you to choose the registry endpoint when you run npm install.

When using https://npm.example.com again as the hypothetical NPM endpoint on Varnish Orca, you can simply run the following command to install the NPM dependencies through Orca:

npm install --registry=https://npm.example.com

You can also fetch individual packages through Orca:

npm install express --registry=https://npm.example.com

What about scoped packages?#

Most of the popular public NPM packages are available in the global scope of the NPM registry. The popular Express package can be installed without defining a scope. Running npm install express is enough to install the package.

Some packages are available within the scope of a user account or organization and have an @<scope>/ prefix.

The @opentelemetry/instrumentation-express package is an example of that: the OpenTelemetry organization published the instrumentation-express package that is available within the @opentelemetry scope.

For every scope, a custom registry can optionally be configured.

Scopes that don’t have a custom registry definition will use the global registry configuration value to fetch its packages.

Use npm config set registry with scoped packages#

When using npm config set registry to configure the registry, the npm config set registry https://npm.example.com command applies the registry to all packages.

The following example commands illustrate how you can configure different registries per scope, including the global scope:

npm config set @opentelemetry:registry https://npm-opentelemetry.example.com
npm config set @angular:registry https://npm-angular.example.com
npm config set registry https://npm.example.com

Here’s the Varnish Orca virtual registry configuration that would reflect these registry endpoints:

virtual_registry:
  registries:
  - name: npm
    remotes:
    - url: https://registry.npmjs.org
  - name: npm-opentelemetry
    remotes:
    - url: https://some.other.registry.example.com
  - name: npm-angular
    remotes:
    - url: https://some.other.registry.example.com

Manually edit your .npmrc file to set registries for scoped packages#

The manual equivalent of the option above would involve adding the following configuration parameters to your .npmrc file:

@opentelemetry:registry=https://npm-opentelemetry.example.com
@angular:registry=https://npm-angular.example.com
registry=https://npm.example.com

Set the --registry option with scoped packages during npm install#

If you would like to route NPM requests for scoped packages through Varnish Orca without changing your .npmrc file, you can still use the --registry option like in one of the previous examples:

npm install @opentelemetry/instrumentation-express --registry=http://npm.example.com