Pm-ninja NPM | npm.io

📦 pm-ninja

A versatile utility package for managing Node/bun js package installations and script execution across multiple package managers (npm, yarn, pnpm, and bun).

Features

🔍 Automatic package manager detection
📦 Smart dependency installation
🛠️ Cross-platform script execution
📝 Package.json management utilities
🚀 Support for npm, yarn, pnpm, and bun

Installation

npm install pm-ninja
# or
yarn add pm-ninja
# or
pnpm add pm-ninja
# or
bun add pm-ninja

Usage

Detecting Package Manager

import { getPackageManager } from 'pm-ninja';

const pm = await getPackageManager();
// Returns: 'npm' | 'yarn' | 'pnpm' | 'bun' | null

Installing Packages

import { installPackages } from 'pm-ninja';

await installPackages({
  dependencies: ['express', 'axios'],
  devDependencies: ['typescript', '@types/node']
});

Running Scripts

import { runScript } from 'pm-ninja';

// Run a script defined in package.json
await runScript('build');

// Run with additional arguments
await runScript('test', ['--watch']);

// Run with additional options
await runScript('start', [], {
  cwd: './packages/frontend',  // Run in a specific directory
  pm: 'yarn',                  // Force a specific package manager
  silent: true                 // Suppress console output
});

Checking Installed Packages

import { getInstalledPackages } from 'pm-ninja';

const packages = await getInstalledPackages();
console.log('Dependencies:', packages.dependencies);
console.log('Dev Dependencies:', packages.devDependencies);

Checking Missing Packages

import { checkMissingPackages } from 'pm-ninja';

const missingPackages = await checkMissingPackages({
  dependencies: ['express', 'react'],
  devDependencies: ['typescript', 'jest']
});

if (missingPackages.dependencies.length > 0) {
  console.log('Missing dependencies:', missingPackages.dependencies);
}
if (missingPackages.devDependencies.length > 0) {
  console.log('Missing dev dependencies:', missingPackages.devDependencies);
}

Reading and Writing package.json

import { readPackageJson, writePackageJson } from 'pm-ninja';

// Read package.json
const packageJson = await readPackageJson();

// Modify package.json content
packageJson.version = '1.0.1';

// Write back to package.json
await writePackageJson(packageJson);

Managing package.json Scripts

import { addScripts } from 'pm-ninja';

await addScripts({
  'build': 'tsc',
  'dev': 'nodemon src/index.ts',
  'test': 'jest'
});

API Reference

`getPackageManager(cwd?: string): Promise<PM | null>`

Detects the package manager being used in the project by checking for lock files.

cwd: Current working directory (defaults to ".")
Returns: Promise resolving to "npm", "yarn", "pnpm", "bun", or null

`installPackages(config: PackageInstallConfig): Promise<void>`

Installs missing packages using the detected package manager.

interface PackageInstallConfig {
  dependencies: string[];
  devDependencies: string[];
}

`runScript(script: string, args?: string[], options?: RunScriptOptions): Promise<ExecResult>`

Runs a package.json script using the detected package manager.

script: Name of the script to run
args: Additional arguments to pass to the script (defaults to [])
options: Additional options (optional)

interface RunScriptOptions {
  cwd?: string;    // Current working directory (defaults to ".")
  pm?: PM;         // Specify package manager, overrides auto-detection
  silent?: boolean; // Suppress console output (defaults to false)
}

`getInstalledPackages(): Promise<InstalledPackages>`

Returns an object containing all installed dependencies and devDependencies from package.json.

interface InstalledPackages {
  dependencies: Record<string, string>;
  devDependencies: Record<string, string>;
}

`checkMissingPackages(config: PackageInstallConfig): Promise<MissingPackages>`

Checks which required packages are not installed.

interface PackageInstallConfig {
  dependencies: string[];
  devDependencies: string[];
}

interface MissingPackages {
  dependencies: string[];
  devDependencies: string[];
}

`readPackageJson(): Promise<PackageJson>`

Reads and parses the package.json file.

Returns: Promise resolving to the parsed package.json content
Throws: Error if package.json cannot be read or parsed

`writePackageJson(packageJson: PackageJson): Promise<void>`

Writes content to package.json file.

packageJson: The package.json content to write
Throws: Error if writing to package.json fails

`addScripts(scripts: PackageJsonScripts): Promise<void>`

Adds or updates scripts in package.json.

interface PackageJsonScripts {
  [key: string]: string;
}

Error Handling

The package includes comprehensive error handling for common scenarios:

No package manager detected
Missing package.json
Failed installations
Script execution errors

Example:

try {
  await installPackages({
    dependencies: ['express'],
    devDependencies: ['typescript']
  });
} catch (error) {
  console.error('Installation failed:', error.message);
}