nx-npm-tools

Installation

Option 1: Global Install (Easiest)

npm i -g nx-npm-tools

If you get permission errors (EACCES), use sudo:

sudo npm i -g nx-npm-tools

Note: Using sudo is simpler, but if you prefer to avoid it, you can fix npm permissions or use npx instead.

Option 2: Use npx (No Installation Required)

You can use npx to run commands without installing:

npx nx-npm-tools reportStation --pro
npx nx-npm-tools publishStation --pro --access public --bump patch

Check Installation

# Check version of nx-npm-tools
nx-npm-tools --version

# See all globally installed packages (for visibility)
npm list -g --depth=0

Prometheus mode (default)

If you run commands without --path, it auto-walks upward until it finds a folder named prometheus and uses it as the station root.

Alias:

• --pro is the same as --prometheus

📖 Playbook

🎯 One-time setup (per station)

Step 1: Map your station

npx nx-npm-tools reportStation --pro --out station-report.md

Review the report to see:

• Relationships: Which packages depend on which (only non-archived/non-ignored packages)
• External private deps: Packages that depend on private/scoped packages not in this station
• Orphaned packages: Packages not used by any other package in the station
• ⚠️ Recommended to move: Packages that are BOTH orphaned AND have external private deps (should be moved to a different station)

Step 2: Preview what would be published

npx nx-npm-tools publishStation --pro --preview --preview-file publish-preview.md --bump patch --access public

This:

• Shows a numbered list in the console (packages that WILL be published)
• Creates publish-preview.md with ALL packages numbered (including already excluded ones)

Step 3: Install latest dependencies

npx nx-npm-tools runOnce:step3 --pro --force

This installs the latest versions of all dependencies for all packages (replaces Renovate).

🔄 Regular publishing workflow

Step 1: Preview what will be published

npx nx-npm-tools publishStation --pro --preview --bump patch --access public

Note: The preview shows packages in dependency order (topological sort) - dependencies are published first.

Always preview first to verify the publish order and packages.

**Step 2: Publish all packages in dependency order**
```bash
npx nx-npm-tools publishStation --pro --access public --bump patch

This will:

• Install dependencies per package
• Build each package
• Bump version (patch/minor/major)
• Publish to npm
• Commit and push changes (solo mode handles git automatically)

Alternative: Publish a single package

cd /path/to/package
npx nx-npm-tools publishOne --cwd . --access public --bump patch

Commands

installLatest (install latest dependencies for all packages)

nx-npm-tools installLatest --pro --force

This command:

• Resolves "latest" and "^0.0.0" dependencies to actual versions from npm
• Installs latest dependencies for all packages in the station
• Optionally force clean installs (removes node_modules and package-lock.json first)

runOnce (deprecated - use step commands instead)

The runOnce command is deprecated. Use the step-by-step commands:

• runOnce:step1 - Map your station
• runOnce:step2 - Preview what would be published
• runOnce:step3 - Install latest dependencies

reportStation (visibility report)

nx-npm-tools reportStation --pro --out station-report.md

publishStation (publish everything in dependency order)

Preview what will be published (recommended first):

nx-npm-tools publishStation --pro --preview --bump patch --access public

Actually publish:

nx-npm-tools publishStation --pro --access public --bump patch

Force clean install per package:

nx-npm-tools publishStation --pro --forceInstall --access public --bump patch

publishOne (publish single package)

nx-npm-tools publishOne --cwd . --access public --bump patch

gitSync (git add + commit + push)

nx-npm-tools gitSync --message "publishing"

statusStation (publishing status report)

# Generate status report showing what's published vs what needs publishing
npx nx-npm-tools statusStation --pro --out station-status.md

# Skip npm registry checks (faster, less accurate)
npx nx-npm-tools statusStation --pro --skip-npm-check

Shows:

• ✅ Published and up-to-date packages
• 📦 Packages needing publication (new or version updates)
• ❌ Packages not published
• ⚠️ Check errors (network/registry issues)

archiveExcluded (move excluded packages to archive)

# Preview what would be moved
nx-npm-tools archiveExcluded --pro --dry-run

# Actually move packages to archive folder
nx-npm-tools archiveExcluded --pro

The archive folder will be created at the same level as the prometheus folder (e.g., if prometheus is at /path/to/prometheus, archive will be at /path/to/archive).

Extras

Excluding packages from station operations

Configure exclusions by package numbers

# View packages from preview file
npx nx-npm-tools excludePackages --pro --preview-file publish-preview.md

# Add packages to exclusion list by numbers
npx nx-npm-tools excludePackages --pro --numbers "1,2,3,5,8"

# Or use the preview file directly
npx nx-npm-tools excludePackages --pro --preview-file publish-preview.md --numbers "1,2,3,5,8"

This adds the specified packages (by their numbers from the preview file) to the exclusion list in .nx-npm-tools.json.

• You can run this multiple times to add more packages
• Use --remove to remove packages: --numbers "1,2" --remove
• The numbers correspond to the order in the preview file

Archive excluded packages (optional but recommended)

# Preview what will be archived
npx nx-npm-tools archiveExcluded --pro --dry-run

# Actually move excluded packages to archive folder
npx nx-npm-tools archiveExcluded --pro

This moves excluded packages to an archive folder (sibling of prometheus root).

Manual configuration

Alternatively, manually edit .nx-npm-tools.json in your station root:

{
  "exclude": {
    "packages": [
      "@scope/old-package",
      "legacy-package"
    ],
    "paths": [
      "old-folder/**",
      "deprecated/*"
    ]
  }
}

Command-line exclusion

nx-npm-tools reportStation --pro --exclude "old-pkg,legacy-pkg"
nx-npm-tools publishStation --pro --exclude "old-pkg,legacy-pkg"