📦 Getting Started with Private Registry

We publish our frontend packages to a custom private registry hosted on Azure DevOps. This guide walks you through how to configure your environment and projects to authenticate and publish or install packages using Yarn, npm, or pnpm.

🔐 1. Authentication to the Private Registry

We use Personal Access Tokens (PAT)  to authenticate with our private Azure registry.

You can generate a PAT at the following URL:
https://dev.azure.com/alzasoft/_usersSettings/tokens 

🔐 Required Scopes

• If you’re only installing packages from the private registry, the Packaging: Read scope is sufficient.
• If you also need to publish packages from your machine, you must enable Packaging: Read & Write.

⏳ Token Expiry
PATs expire after a set period — make sure to choose a reasonable expiration date when creating the token. The maximum allowed is one year, so consider setting a reminder to renew it before it expires.

🔒 Token Format

If your token is 123, then in .yarnrc.yml:

npmAuthIdent: u:123

🧶 2. Yarn Setup (.yarnrc.yml)

📁 Project-level .yarnrc.yml

Create or update .yarnrc.yml in your project root:

npmScopes:
  alza: // ← Named scope, must match .yarnrc.yml on the user level
    npmRegistryServer: "https://alzasoft.pkgs.visualstudio.com/Alza.FE/_packaging/AlzaFE/npm/registry/"
    npmAlwaysAuth: true

🏠 User-level .yarnrc.yml

Create or update your global .yarnrc.yml:

• Windows: C:/Users/<you>/.yarnrc.yml
• macOS/Linux: ~/.yarnrc.yml

npmScopes:
  alza: // ← Named scope, must match .yarnrc.yml in the project
    npmAuthIdent: u:<YOUR_PAT>

📦 3. npm Setup (.npmrc)

📁 Project-level .npmrc

Create a .npmrc in your project:

@alza:registry=https://alzasoft.pkgs.visualstudio.com/Alza.FE/_packaging/AlzaFE/npm/registry/
//alzasoft.pkgs.visualstudio.com/Alza.FE/_packaging/AlzaFE/npm/registry/:always-auth=true

🏠 User-level .npmrc

Global .npmrc (usually at ~/.npmrc):

# NOTE: No 'u:' prefix for npm, just raw token
//alzasoft.pkgs.visualstudio.com/Alza.FE/_packaging/AlzaFE/npm/registry/:_authToken=<YOUR_PAT>

🚀 4. pnpm Setup

📁 Project-level .npmrc

pnpm uses .npmrc just like npm:

@alza:registry=https://alzasoft.pkgs.visualstudio.com/Alza.FE/_packaging/AlzaFE/npm/registry/
//alzasoft.pkgs.visualstudio.com/Alza.FE/_packaging/AlzaFE/npm/registry/:always-auth=true

🏠 User-level .npmrc

# Auth token for registry
//alzasoft.pkgs.visualstudio.com/Alza.FE/_packaging/AlzaFE/npm/registry/:_authToken=<YOUR_PAT>

🏗 5. Creating a Package to Publish

📁 Example package.json

When creating a new package, your package.json should include the following:

{
  ...,
  "publishConfig": {
    "registry": "https://alzasoft.pkgs.visualstudio.com/Alza.FE/_packaging/AlzaFE/npm/registry/"
  }
}

📤 6. Steps to Publish

1. Build your package

Make sure the package is ready for publishing (e.g., built into dist folder):

npm run build

2. Publish

yarn npm publish --access restricted
# or
npm publish --access restricted
# or
pnpm publish --access restricted

⚠️ Make sure your PAT has write permissions and your publishConfig.registry is correctly set.

✅ 7. Consuming a Package

Install the package like any other dependency:

yarn add @alza/button
# or
npm install @alza/button
# or
pnpm add @alza/button

If you’ve configured the registry correctly in your .yarnrc.yml or .npmrc, it will fetch it from the private registry.

🧪 Troubleshooting

• 401 Unauthorized: Make sure your PAT is correct and has the required scope.
• Package not found: Confirm the package is published and the scope is correctly prefixed (@alza/).
• Authentication issues: Double-check that you’re using the correct .yarnrc.yml or .npmrc files and paths.