Installing npm Packages

How to install and consume packages from DepAegis, including version pinning, scoped packages, production builds, and troubleshooting common errors.

Prerequisites

Before installing packages from DepAegis, ensure you have:

A DepAegis account with read (or higher) access to the target organization.
An access token configured in your .npmrc.
Your .npmrc pointing to DepAegis for the relevant scope or as the default registry.

If you haven't configured npm yet, follow the Configuring npm guide to set up your registry and authentication.

Installing a Package

Install a package from DepAegis the same way you would from any npm registry:

# Add to dependencies
npm install @myorg/ui-components

# Add to devDependencies
npm install --save-dev @myorg/eslint-config

npm resolves the package from DepAegis based on your .npmrc configuration, downloads the tarball, and adds the entry to your package.json.

Scoped Packages

When your .npmrc maps a scope to DepAegis, all @scope/package installs are routed there automatically:

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

# Installs from DepAegis
npm install @myorg/ui-components
npm install @myorg/utils @myorg/design-tokens

See Scoped Packages for a complete guide to setting up and working with scopes in DepAegis.

Version Ranges and Exact Versions

npm supports several ways to specify which version to install:

Syntax	Example	Meaning
No version	`npm install @myorg/ui`	Latest version matching ranges in `package.json`
Caret range	`npm install @myorg/ui@^1.2.0`	>=1.2.0 <2.0.0 (compatible with 1.2.0)
Tilde range	`npm install @myorg/ui@~1.2.0`	>=1.2.0 <1.3.0 (patch-level updates only)
Exact version	`npm install @myorg/ui@1.2.3`	Exactly version 1.2.3
Distribution tag	`npm install @myorg/ui@beta`	Version tagged as `beta`

Using in package.json

When you run npm install, npm adds an entry to your package.json. You can also edit it manually:

{
  "dependencies": {
    "@myorg/ui-components": "^2.1.0",
    "@myorg/design-tokens": "~1.4.2"
  },
  "devDependencies": {
    "@myorg/eslint-config": "1.0.0",
    "@myorg/tsconfig": "^3.0.0"
  }
}

Pinning vs ranges

Caret (^) — allows minor and patch updates. Good for libraries you trust to follow semver.
Tilde (~) — allows patch updates only. Safer for critical dependencies.
Exact (1.2.3) — no updates without explicit change. Maximum reproducibility.

For applications (not libraries), pinning exact versions in package.json and using npm ci in CI ensures fully deterministic builds.

npm ci for Production Builds

npm ci (Clean Install) is the recommended command for CI/CD pipelines and production deployments. It installs dependencies from package-lock.json exactly, without modifying it:

npm ci

How it differs from npm install

Behavior	`npm install`	`npm ci`
Reads lockfile	Yes (as suggestion)	Yes (as strict source of truth)
Updates lockfile	Yes	No — fails if missing or out of sync
Deletes `node_modules`	No	Yes — clean slate every time
Speed	Variable	Faster (no resolution step)
Use case	Development	CI/CD, production

npm ci requires a package-lock.json that is in sync with package.json. If they differ, the command fails. Always commit your lockfile.

Verifying Package Integrity

npm automatically verifies the integrity hash of every package it downloads against the value in the registry's metadata. This is stored in package-lock.json:

"integrity": "sha512-abc123...",
"resolved": "https://app.depaegis.com/@myorg/ui-components/-/ui-components-2.1.0.tgz"

If the hash doesn't match, npm refuses to install the package. This protects against tampering and corrupted downloads.

To manually verify all installed packages:

npm audit

DepAegis adds an extra layer of protection: every published package is cryptographically signed with SLSA provenance, so you can verify the package was built by a trusted CI pipeline.

Troubleshooting

403 Forbidden

This usually means one of:

Your access token is invalid or expired. Regenerate it from the DepAegis dashboard.
You don't have read access to the organization that owns the package. Contact your admin.
The package is quarantined due to a vulnerability. Check the DepAegis dashboard for details.

# Verify your token is accepted (404 = token OK, unknown package)
npm view @myorg/your-package --registry=https://app.depaegis.com/api/v1/npm/

404 Not Found

The package or version doesn't exist in DepAegis:

Check the package name for typos (including scope prefix).
Verify the version exists: check the DepAegis dashboard or run npm view @myorg/package versions.
Ensure your .npmrc routes the correct scope to DepAegis.
If using upstream proxy, the package may not have been cached yet. Try npm install again.

Authentication errors (ENEEDAUTH)

npm ERR! code ENEEDAUTH
npm ERR! need auth auth required for publishing

Your token is not being sent. Verify:

The _authToken line in .npmrc matches the registry URL exactly (including trailing slash).
The environment variable DEPAEGIS_TOKEN is set if you're using a variable reference.
The token hasn't been revoked or expired.

SSL certificate errors

DepAegis serves all endpoints with a trusted CA certificate, so npm works out of the box. If you see SSL errors, the cause is almost always a corporate proxy or TLS-inspection appliancere-signing traffic with its own CA. Add your organization's root CA:

npm config set cafile /path/to/corporate-ca.pem

Do not disable TLS verification (strict-ssl false) to work around it.

← Previous

Publishing npm Packages

Scoped Packages