Use npm scopes

Azure DevOps Services | TFS 2018 | TFS 2017

Scopes are built into npm and are a way of grouping packages together. In Azure DevOps Services and in npmjs.com, you can publish and use both scoped and unscoped packages.

Scopes are also the npm client's only native affordance to use multiple registries/feeds. They allow you to separate your private packages from npmjs.com packages by prefixing your packages with a @scope: e.g. @fabrikam/fiber-core and configuring your .npmrc file to only use a Azure Artifacts feed for that @scope.

Set up

To use a Azure Artifacts feed with a scope, follow the instructions below, but append your scope to both lines in the project .npmrc file.

The Connect to feed dialog will generate an appropriately-formatted token that you can place into your .npmrc file with a lifespan of 90 days.

If you want to create a token that lasts longer than 90 days, skip to the second method below.

90-day token:

  1. From Azure Artifacts, select Connect to feed

  2. Select npm.

  3. Click Generate npm credentials and copy them to add them to your user .npmrc manually:

  1. From the Packages page, select Connect to feed

  2. Select npm.

  3. Click Generate npm credentials and copy them to add them to your user .npmrc manually:

    Connect to feed from Azure Artifacts Linux/Mac credentials

Create a token that lasts longer than 90 days:

  1. Navigate to security and generate a PAT with a narrow scope of "Packaging (read and write)".
  2. Base64 encode the PAT. On Windows you can use...

    [Convert]::ToBase64String([system.Text.Encoding]::UTF8.GetBytes("YOUR_PAT_GOES_HERE"))
    
  3. In your $home/.npmrc add the following lines replacing account, feedname, username, PAT, and email.

    //pkgs.dev.azure.com/<yourorganization>/_packaging/<yourfeed>/npm/registry/:username=YOUR-USERNAME
    //pkgs.dev.azure.com/<yourorganization>/_packaging/<yourfeed>/npm/registry/:_password=BASE64-ENCODED-PAT-GOES-HERE
    //pkgs.dev.azure.com/<yourorganization>/_packaging/<yourfeed>/npm/registry/:email=YOUREMAIL@EXAMPLE.COM
    //pkgs.dev.azure.com/<yourorganization>/_packaging/<yourfeed>/npm/registry/:always-auth=true
    

Then, replace:

  • registry=<your feed URL> with
  • @fabrikam:registry=<your feed URL>

Upstreams or scopes?

Scopes add an additional restriction when naming your packages: each package name must start with @<scope>. If you're ok with this limitation, and don't intend to ever publish your private packages to npmjs.com, scopes are an alternative to upstream sources.

If you do intend to publish private packages to npmjs.com, we recommend not using scopes unless you intend to publish your packages to npmjs.com with the scope intact; if you remove the scope when transitioning the package from Azure Artifacts to npmjs.com, you'll need to update any package.json references accordingly.