Avoid postinstall by using optionalDependencies for each platform

[sverrejoh]

Summary of the Pull Request

Uses npm's optionalDependencies with os and cpu fields to provide the azureauth binary through the normal package installation flow, making the postinstall download optional.

References and Relevant Issues

• Same pattern used by esbuild, SWC, sharp
• pnpm 10 blocks lifecycle scripts by default
• npm RFC: Platform-Specific Dependencies

Detailed Description of the Pull Request / Additional comments

Problem

The postinstall download approach has compatibility and reliability issues:

• pnpm 10+ - blocks lifecycle scripts by default for security
• yarn PnP - not recommended due to unplugging behavior
• --ignore-scripts - when lifecycle scripts are disabled
• Network reliability - downloads outside the package fetch stage miss retry mechanisms, caching, and mirrors

Solution

Creates three platform-specific packages under the @microsoft npm scope:

• @microsoft/azureauth-darwin-arm64 - macOS ARM64
• @microsoft/azureauth-darwin-x64 - macOS x64
• @microsoft/azureauth-win32-x64 - Windows x64

Package manager support

Package Manager	Behavior
npm 7+	Installs only matching platform package
pnpm	Installs only matching platform package
bun	Installs only matching platform package
yarn 2+	Downloads all, keeps matching

Fallback

The postinstall script still exists for backwards compatibility. It checks if the binary is already available and exits early:

if (isOptionalDepInstalled()) {
  console.log("azureauth binary available via platform-specific package, skipping download");
  return;
}

This handles unsupported platforms (Linux), older package managers, or disabled optionalDependencies.

Validation Steps Performed

Test the publish script (dry run)

cd packages/node-azureauth
yarn bundle
yarn publish-all:dry-run

Test installation manually (on macOS or Windows)

# Pack the packages
cd packages/azureauth-darwin-arm64 && npm pack
cd packages/node-azureauth && npm pack

# In a test directory, install from tarballs
mkdir /tmp/test && cd /tmp/test && npm init -y
npm install /path/to/azureauth-0.13.0.tgz

# Check that the binary was downloaded or resolved
ls node_modules/azureauth/bin/azureauth/

Note: Full binary testing requires macOS or Windows (Linux binaries not available).

PR Checklist

• Closes Avoid postinstall by using optionalDependencies for each platform #104
• Tests added/passed
• Documentation updated