Quick Start: npm

Get your first npm package published and consumed through DepAegis in under 5 minutes. This guide walks you through creating an access token, configuring npm, publishing a package, and installing it on another machine.

Prerequisites

Before you begin, make sure you have the following:

• Node.js 18+ — run node --version to check
• npm 9+ — run npm --version to check
• A DepAegis account — sign up free at app.depaegis.com

Step 1: Create an Access Token

DepAegis uses personal access tokens to authenticate npm CLI operations. You'll need a token with publish permissions to push packages and read permissions to install them.

1. Open your DepAegis dashboard in a browser.
2. Navigate to Settings → Access Tokens.
3. Click Create Token.
4. Give the token a descriptive name (e.g., npm-ci-publish).
5. Select the Publish & Read scope.
6. Click Generate and copy the token value.

Step 2: Configure npm to Use DepAegis

Configure your npm client to point to your DepAegis registry. You can set this up per-project (recommended) or globally.

Use the access token from Step 1 as YOUR_TOKEN.

Per-Project Configuration (Recommended)

Create or edit an .npmrc file in your project root:

@myorg:registry=https://app.depaegis.com/api/v1/npm/
//app.depaegis.com/:_authToken=YOUR_TOKEN

This routes only @myorg-scoped packages through DepAegis while leaving public npm packages unaffected. Replace @myorg with your DepAegis organization scope.

Global Configuration

To route all npm packages through DepAegis (including public packages via the upstream proxy), configure your global ~/.npmrc:

registry=https://app.depaegis.com/api/v1/npm/
//app.depaegis.com/:_authToken=YOUR_TOKEN

@myorg:registry=https://app.depaegis.com/api/v1/npm/
//app.depaegis.com/:_authToken=YOUR_TOKEN

registry=https://app.depaegis.com/api/v1/npm/
//app.depaegis.com/:_authToken=YOUR_TOKEN

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

Step 3: Verify Your Configuration

DepAegis uses token-based auth only — no interactive npm login needed. Confirm your registry and token are picked up:

npm config get registry

This should output https://app.depaegis.com/api/v1/npm/. npm sends the _authToken from your .npmrc automatically on every request to that host.

Step 4: Publish a Package

Create a simple package or use an existing one. Make sure your package.json includes the correct scope and publishConfig to target DepAegis:

{
  "name": "@myorg/example-package",
  "version": "1.0.0",
  "description": "An example package published to DepAegis",
  "main": "index.js",
  "publishConfig": {
    "registry": "https://app.depaegis.com/api/v1/npm/",
    "access": "restricted"
  }
}

The publishConfig.registry field ensures that npm publish always targets DepAegis, even if your global npm registry is set to the public npmjs.org. The access field controls visibility — restricted means only members of your organization can see and install the package.

Now publish the package:

npm publish

On success, you'll see output similar to:

+ @myorg/example-package@1.0.0

Publishing a New Version

When you need to release an update, bump the version and publish again:

# Patch bump (1.0.0 -> 1.0.1)
npm version patch
npm publish

# Minor bump (1.0.0 -> 1.1.0)
npm version minor
npm publish

# Major bump (1.0.0 -> 2.0.0)
npm version major
npm publish

Step 5: Install from DepAegis

On any machine with the DepAegis registry configured, install your package the same way you would install any npm package:

npm install @myorg/example-package

npm fetches the package from DepAegis, verifies the integrity hash, and adds it to your package.json and package-lock.json.

Install a Specific Version

npm install @myorg/example-package@1.2.0

Install a Tagged Version

npm install @myorg/example-package@beta

Step 6: Verify in the DepAegis Dashboard

After publishing, open your DepAegis dashboard to review the package details:

1. Navigate to Organizations → @myorg → Packages to see your newly published package listed.
2. Click on @myorg/example-package to open the package detail page.
3. Review the Security tab to see the vulnerability scan results. If any vulnerabilities were detected, they are listed with severity ratings and remediation suggestions.
4. Check the SBOM tab to view the auto-generated Software Bill of Materials in CycloneDX format. You can download the SBOM as a JSON or XML file for compliance reporting.
5. View the Versions tab to see all published versions, their publish dates, and integrity hashes.

Next Steps

Now that you've published and consumed your first npm package through DepAegis, here are some recommended next steps:

• Scoped Packages — learn how to manage multiple scopes and organizations.
• Vulnerability Scanning — understand how DepAegis scans packages and how to respond to findings.
• Dependency Firewall — set up OPA policies to block vulnerable or non-compliant packages.
• CI/CD Integration — automate publishing from your GitHub Actions, GitLab CI, or Azure DevOps pipelines.
• Signing & Provenance — add SLSA provenance and Sigstore keyless signing to your packages.