Configuring npm

Learn how to configure the npm client to use DepAegis as your private package registry, including authentication, scoped packages, and upstream proxying.

Setting Up .npmrc

The .npmrc file controls how npm interacts with registries. You can configure DepAegis at three levels:

The simplest configuration points npm to your DepAegis registry:

registry=https://app.depaegis.com/api/v1/npm/
//app.depaegis.com/:_authToken=${DEPAEGIS_TOKEN}

Auth Token Configuration

DepAegis uses Bearer token authentication. Generate an access token from the DepAegis dashboard under Settings → Access Tokens, then configure it in your .npmrc:

Using an environment variable (recommended)

//app.depaegis.com/:_authToken=${DEPAEGIS_TOKEN}

Then set the environment variable in your shell or CI configuration:

export DEPAEGIS_TOKEN="dap_abc123def456..."

Using a plain token

//app.depaegis.com/:_authToken=dap_abc123def456...

Token-Based Authentication Only

DepAegis does not support interactive npm login (adduser). Authentication is token-based: create an access token in the dashboard and reference it in your .npmrc as shown above. npm sends it automatically on every request to app.depaegis.com.

Scoped Registries

If you want to use DepAegis only for specific scopes (e.g. @myorg) while keeping the default registry pointing to the public npm registry:

# Default: public npm registry
registry=https://registry.npmjs.org/

# @myorg scope goes to DepAegis
@myorg:registry=https://app.depaegis.com/api/v1/npm/
//app.depaegis.com/:_authToken=${DEPAEGIS_TOKEN}

With this configuration, npm install @myorg/ui-components pulls from DepAegis, while npm install lodash pulls from the public registry.

publishConfig in package.json

To ensure a package is always published to DepAegis regardless of the user's default registry, add publishConfig to your package.json:

{
  "name": "@myorg/design-tokens",
  "version": "1.2.0",
  "publishConfig": {
    "registry": "https://app.depaegis.com/api/v1/npm/"
  }
}

This overrides the registry setting only for npm publish, so developers can keep their default registry pointing elsewhere.

Verifying Configuration

Check your active npm configuration at any time:

npm config list

For a more detailed view including all sources:

npm config list --long

Verify the registry is set correctly:

npm config get registry
# Should output: https://app.depaegis.com/api/v1/npm/

Then confirm auth works by listing a package from your feed (any package name — a 404 for an unknown package means the token was accepted):

npm view @myorg/your-package --registry=https://app.depaegis.com/api/v1/npm/

Proxy / Upstream Configuration

DepAegis can act as a proxy (upstream cache) for the public npm registry. When enabled, requests for packages not found in DepAegis are forwarded to the upstream registry, and the response is cached locally.

How it works

1. A developer runs npm install react.
2. DepAegis checks if react exists in the private registry.
3. If not found and upstream is configured, DepAegis fetches it from the public registry and caches it.
4. Subsequent requests for react are served from cache.

Configuring the client for proxy mode

When DepAegis is configured as an upstream proxy, set your default registry to DepAegis for all packages:

registry=https://app.depaegis.com/api/v1/npm/
//app.depaegis.com/:_authToken=${DEPAEGIS_TOKEN}

# Optional: bypass cache for specific packages
# @public:registry=https://registry.npmjs.org/

Complete Example .npmrc

A production-ready per-project .npmrc for a team using DepAegis as both a private registry and an upstream proxy:

# DepAegis registry (acts as upstream proxy for public packages too)
registry=https://app.depaegis.com/api/v1/npm/

# Authentication
//app.depaegis.com/:_authToken=${DEPAEGIS_TOKEN}

# Strict SSL (default: true, set to false only for self-signed certs)
//app.depaegis.com/:strict-ssl=true

# Verify package integrity
//app.depaegis.com/:always-auth=true