Skip to main content

npm Package Management

NPM Package Management Instruction Set – Strict Enforcement

Purpose This instruction set defines strict rules for maintaining package.json files and ensuring that npm is the only package manager used. It ensures reproducibility across multiple repositories.

Global Assumptions​

  • npm is the enforced package manager
  • package-lock.json must always be present and committed
  • Node.js version should match the .nvmrc or engines field in package.json
  • No yarn or other package managers are allowed
  • All repositories must produce identical installs with npm ci

Reason Enforcing a single package manager ensures reproducible builds, consistent dependency versions, and reduces environment drift.

1. Enforcing npm as the Package Manager​

Rules​

  • Include packageManager field in package.json:
{
  "packageManager": "npm@9.8.1"
}
  • Add a preinstall script to check the package manager:
"scripts": {
  "preinstall": "node ./scripts/check-npm.js"
}
  • check-npm.js example:
const pkgManager = process.env.npm_config_user_agent;
if (!pkgManager || !pkgManager.startsWith('npm')) {
  console.error('ERROR: Only npm is supported. Aborting.');
  process.exit(1);
}

Reason Prevents accidental use of Yarn or other package managers, which can break package-lock.json consistency.

2. Package Lock Enforcement​

  • Always commit package-lock.json
  • Use npm ci for automated CI/CD builds
  • Do not allow npm install in CI/CD for reproducibility

Reason package-lock.json ensures exact dependency versions across machines and environments.

3. Dependency Management Rules​

  • Use npm install --save for runtime dependencies
  • Use npm install --save-dev for dev dependencies
  • Remove unused dependencies regularly
  • Pin versions explicitly if necessary for reproducibility

Reason Explicit dependency management prevents version drift and broken builds across repositories.

4. Scripts Enforcement​

  • Include scripts for:

    • lint
    • build
    • test
    • preinstall (to check npm)

  • Avoid scripts that rely on non-npm tools unless documented

Reason Standardized scripts maintain reproducibility and enforce repository-wide conventions.

5. Copilot Instructions When This Set is Applied​

  • Always generate package.json with packageManager field
  • Include preinstall npm-check script
  • Do not generate Yarn-specific fields (yarn.lock) or scripts
  • Always ensure reproducible installs with npm ci
  • Maintain the same dependency versions and scripts across repositories

This instruction set is modular and can be applied to any repository alongside main TypeScript/CDK instructions to strictly enforce npm package management.