📦 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);
}

🤝 Contributing

Contributions are welcome! Check back soon for contribution guidelines.

📝 License

This project is licensed under the MIT License .

Acknowledgments

• Built with TypeScript
• Inspired by the need for unified package management across different package managers