Publishing npm Packages

Everything you need to know about publishing npm packages to DepAegis, from your first publish to advanced versioning, distribution tags, and deprecation.

Prerequisites

Before publishing, make sure you have:

• A DepAegis account with publish permissions for the target organization or scope.
• An access token configured in your .npmrc.
• A correctly configured package.json with a unique name and version.

Publishing for the First Time

Navigate to your package directory and run:

npm publish

If your package.json has a publishConfig or your default registry is DepAegis, the package is published directly:

{
  "name": "@myorg/ui-components",
  "version": "1.0.0",
  "publishConfig": {
    "registry": "https://app.depaegis.com/api/v1/npm/"
  }
}

If you need to specify the registry inline:

npm publish --registry=https://app.depaegis.com/api/v1/npm/

After publishing, the package appears in the DepAegis dashboard. DepAegis automatically scans it for vulnerabilities and generates an SBOM.

Scoped vs Unscoped Packages

Packages can be scoped (e.g. @myorg/package) or unscoped (e.g. my-package).

Versioning and SemVer

DepAegis follows the standard npm versioning rules based on semantic versioning (semver): MAJOR.MINOR.PATCH.

• MAJOR — breaking changes
• MINOR — new features, backwards-compatible
• PATCH — bug fixes, backwards-compatible

Use npm version to bump the version before publishing:

npm version patch   # 1.0.0 -> 1.0.1
npm version minor   # 1.0.1 -> 1.1.0
npm version major   # 1.1.0 -> 2.0.0

This updates package.json and creates a git commit and tag automatically.

Distribution Tags

Distribution tags (dist-tags) let you label specific versions. The default tag is latest.

Publishing with a tag

npm publish --tag beta

This publishes the package under the beta tag instead of latest.

Managing tags

# List all dist-tags
npm dist-tag ls @myorg/ui-components

# Add a tag to an existing version
npm dist-tag add @myorg/ui-components@2.0.0-rc.1 next

# Remove a tag
npm dist-tag rm @myorg/ui-components beta

Installing a tagged version

npm install @myorg/ui-components@beta

Pre-release Versions

Pre-release versions follow the semver format with a hyphenated suffix: MAJOR.MINOR.PATCH-prerelease.N.

# Using npm version
npm version prerelease   # 1.0.0 -> 1.0.1-0
npm version prerelease   # 1.0.1-0 -> 1.0.1-1

# With a pre-id
npm version preminor --preid alpha   # 1.0.1-1 -> 1.1.0-alpha.0
npm version prerelease --preid alpha # 1.1.0-alpha.0 -> 1.1.0-alpha.1

Publish a pre-release:

npm publish --tag next

Updating an Existing Package

To update a package you've already published:

1. Make your changes.
2. Bump the version: npm version patch (or minor, major).
3. Publish: npm publish.

# Full workflow
npm version patch && npm publish

Automating with CI/CD

For production packages, automate publishing through your CI/CD pipeline. This ensures every publish is traced, signed, and scanned.

A minimal GitHub Actions example:

- name: Publish to DepAegis
  run: npm publish
  env:
    DEPAEGIS_TOKEN: ${{ secrets.DEPAEGIS_TOKEN }}

Deprecating Packages

If a package version is outdated or has critical bugs, deprecate it instead of deleting it. Deprecated versions remain installable but show a warning:

# Deprecate a specific version
npm deprecate @myorg/ui-components@1.0.0 "Use v1.0.1 or later - fixes critical XSS bug"

# Deprecate the entire package
npm deprecate @myorg/ui-components "This package has been renamed to @myorg/components"

Deleting Packages

Deleting packages from DepAegis is available through the dashboard or the REST API. The npm CLI does not support unpublish against private registries.

Via Dashboard

1. Navigate to the package in the DepAegis dashboard.
2. Go to Settings → Danger Zone.
3. Click Delete version or Delete package.

Via REST API

curl -X DELETE \
  -H "Authorization: Bearer $DEPAEGIS_TOKEN" \
  "https://app.depaegis.com/@myorg%2Fui-components/1.0.0"