Use npm scopes to manage packages in Azure Artifact

Azure DevOps Services | Azure DevOps Server | Azure DevOps Server 2022

npm scopes help categorize related packages into groups. They let you create packages with the same names as packages created by other users without conflicts. By using scopes, you can separate public and private packages by adding the scope prefix @scopeName and configuring the .npmrc file to use a feed with that scope.

Azure Artifacts supports publishing and downloading both scoped and unscoped packages from feeds or public registries. npm scopes are especially useful when you're working with self-hosted on-premises servers that don't have internet access, because configuring upstream sources in those scenarios isn't feasible. In summary, when you use scopes:

• You don't have to worry about name collisions.
• You don't need to change the npm registry to install or publish packages.
• Each npm organization or user has its own scope, and only the owner or scope members can publish packages to that scope.

Prerequisites

Connect to your feed

Before you configure npm scopes, connect your project to your Azure Artifacts feed. Make sure that you complete the prerequisites and create a feed, and then follow these steps.

Azure Artifacts recommends using two separate .npmrc files. Keep one file in your user directory to store your credentials, and keep the second file in the same directory as your package.json file to store your feed-specific configuration.

vsts-npm-auth -config .npmrc

Scope setup

To use scopes with Azure Artifacts, update your project .npmrc file so that the scoped packages you publish or install resolve through your feed. Replace registry=<YOUR_SOURCE_URL> with @ScopeName:registry=<YOUR_SOURCE_URL>.

Also update your package.json file to include both the scope name and the package name, for example: { "name": "@ScopeName/PackageName" }. The following examples show how to configure organization-scoped and project-scoped feeds.

• Organization-scoped feed:

  @ScopeName:registry=https://pkgs.dev.azure.com/<ORGANIZATION_NAME>/_packaging/<FEED_NAME>/npm/registry/
  
  always-auth=true
  

  {
    "name": "@ScopeName/PackageName"
  }
  

• Project-scoped feed:

  @ScopeName:registry=https://pkgs.dev.azure.com/<ORGANIZATION_NAME>/<PROJECT_NAME>/_packaging/<FEED_NAME>/npm/registry/
  
  always-auth=true
  

  {
    "name": "@ScopeName/PackageName"
  }
  

Example

• The .npmrc file:

  @local:registry=https://pkgs.dev.azure.com/FabrikamOrg/NpmDemo/_packaging/FabrikamFeed/npm/registry/
  
  always-auth=true
  

• The package.json file:

  {
    "name": "@demo/js-e2e-express-server",
    "version": "2.0.0",
    "description": "JavaScript server written with Express.js",
    "main": "index.js",
    "directories": {
      "doc": "docs",
      "test": "test"
    }
  }
  

Publish scoped packages

After you configure your scope and update your project files, open a command prompt window, navigate to your project directory, and run the following command to publish your scoped package. In the previous example, the package is published under the @local scope.

npm publish

Upstream sources vs scopes

Upstream sources provide the most flexibility. By using upstream sources, you can consume both scoped and unscoped packages from your Azure Artifacts feed while also using packages from public registries such as npmjs.com. This approach works well when you want a single feed to act as the main source for both internal packages and approved external dependencies.

Scopes are more restrictive, but they can still be a practical option in the right scenario. When you use scopes, each package name must start with @<scope>, which means you need to adopt and keep that naming convention across your packages. For example, if you publish a package as @local/my-package, you must continue to use that scoped name anywhere the package is referenced.

This requirement can add overhead, especially if you plan to publish the same packages to a public registry later. If you remove scopes when you deploy your packages, you must also update the corresponding references in your package.json files and any dependent projects.

Even with those limitations, scopes can serve as a viable alternative when upstream sources aren't practical. This is especially true in isolated or self-hosted environments where access to public registries isn't available and you want to avoid package name collisions while keeping packages organized within your feed.

Related content

• Npm audit

• Publish npm packages with Azure Pipelines (YAML/Classic)

• Use packages from the npm registry