tessl/npm-pm2

Production process manager for Node.JS applications with a built-in load balancer.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Configuration Management

Name: tessl/npm-pm2
Author: tessl

PM2 configuration management capabilities for getting, setting, and persisting configuration values. Includes state persistence operations for saving and restoring process configurations across system restarts.

Capabilities

Configuration Operations

Manage PM2 configuration settings including runtime and persistent configuration.

/**
 * Get PM2 configuration value
 * @param key - Configuration key (optional, returns all config if not provided)
 * @param callback - Called with configuration value
 */
function get(key?: string, callback?: (err: Error) => void): void;

/**
 * Set PM2 configuration value
 * @param key - Configuration key
 * @param value - Configuration value
 * @param callback - Called when value is set
 */
function set(key: string, value: any, callback?: (err: Error) => void): void;

/**
 * Set multiple PM2 configuration values
 * @param values - Configuration values as string
 * @param callback - Called when values are set
 */
function multiset(values: string, callback?: (err: Error) => void): void;

/**
 * Unset PM2 configuration value
 * @param key - Configuration key to unset
 * @param callback - Called when value is unset
 */
function unset(key: string, callback?: (err: Error) => void): void;

Usage Examples:

// Get specific configuration value
pm2.get('pm2_home', (err) => {
  if (err) throw err;
  console.log('PM2 home directory retrieved');
});

// Get all configuration
pm2.get((err) => {
  if (err) throw err;
  console.log('All configuration retrieved');
});

// Set configuration value
pm2.set('log-date-format', 'YYYY-MM-DD HH:mm:ss Z', (err) => {
  if (err) throw err;
  console.log('Log date format updated');
});

// Set multiple values
pm2.multiset('log-date-format="YYYY-MM-DD" max-memory-restart=1G', (err) => {
  if (err) throw err;
  console.log('Multiple configuration values set');
});

// Remove configuration value
pm2.unset('log-date-format', (err) => {
  if (err) throw err;
  console.log('Log date format unset');
});

State Persistence

Save and restore PM2 process configurations for system restart recovery.

/**
 * Save current process list to dump file
 * @param callback - Called when dump is saved
 */
function dump(callback: (err: Error, result: any) => void): void;

/**
 * Restore processes from dump file
 * @param callback - Called when processes are restored
 */
function resurrect(callback: (err: Error, result: any) => void): void;

/**
 * Clear saved dump file
 * @param callback - Called when dump is cleared
 */
function clearDump(callback: (err: Error, result: any) => void): void;

/**
 * Enable or disable automatic dumping
 * @param callback - Called when autodump setting is configured
 */
function autodump(callback: (err: Error, result: any) => void): void;

Usage Examples:

// Save current process configuration
pm2.dump((err, result) => {
  if (err) throw err;
  console.log('Process list saved to dump file');
});

// Restore processes from saved configuration
pm2.resurrect((err, result) => {
  if (err) throw err;
  console.log('Processes restored from dump file');
});

Module Management

Install and manage PM2 modules for extending functionality.

/**
 * Install PM2 module
 * @param module_name - Name of module to install
 * @param options - Installation options
 * @param callback - Called when installation completes
 */
function install(module_name: string, options?: InstallOptions, callback?: (err: Error) => void): void;

/**
 * Uninstall PM2 module
 * @param module_name - Name of module to uninstall
 * @param callback - Called when uninstallation completes
 */
function uninstall(module_name: string, callback?: (err: Error) => void): void;

interface InstallOptions {
  /** Install from tarball */
  tarball?: boolean;
  /** Perform installation */
  install?: boolean;
  /** Docker mode */
  docker?: boolean;
  /** Use v1 API */
  v1?: boolean;
  /** Safe mode installation */
  safe?: boolean | number;
}

Usage Examples:

// Install module
pm2.install('pm2-logrotate', (err) => {
  if (err) throw err;
  console.log('Module installed successfully');
});

// Install with options
pm2.install('pm2-server-monit', { safe: true }, (err) => {
  if (err) throw err;
  console.log('Module installed in safe mode');
});

// Uninstall module
pm2.uninstall('pm2-logrotate', (err) => {
  if (err) throw err;
  console.log('Module uninstalled successfully');
});

Utility Services

Additional utility functions for static file serving and system integration.

/**
 * Serve static files
 * @param path - Path to serve files from
 * @param port - Port number (default: 8080)
 * @param options - Serve options
 * @param callback - Called when server starts
 */
function serve(path?: string, port?: number, options?: ServeOptions, callback?: (err: Error) => void): void;

interface ServeOptions {
  /** Single Page Application mode */
  spa?: boolean;
  /** Basic authentication username */
  basic_auth_username?: string;
  /** Basic authentication password */
  basic_auth_password?: string;
  /** Monitor URL path */
  monitor?: string;
}

Usage Examples:

// Serve current directory on default port
pm2.serve((err) => {
  if (err) throw err;
  console.log('Static file server started on port 8080');
});

// Serve specific directory on custom port
pm2.serve('./public', 3000, (err) => {
  if (err) throw err;
  console.log('Static file server started on port 3000');
});

// Serve with options
pm2.serve('./dist', 8080, {
  spa: true,
  basic_auth_username: 'admin',
  basic_auth_password: 'secret'
}, (err) => {
  if (err) throw err;
  console.log('SPA server started with basic auth');
});

Version and System Information

Get PM2 version and system information.

/**
 * Get PM2 version information
 * @param callback - Called with version information
 */
function getVersion(callback?: (err: Error) => void): void;

/**
 * Test connection to PM2 daemon
 * @param callback - Called with ping result
 */
function ping(callback?: (err: Error) => void): void;

/**
 * Update PM2 daemon
 * @param callback - Called when update completes
 */
function update(callback?: (err: Error) => void): void;

Usage Examples:

// Get PM2 version
pm2.getVersion((err) => {
  if (err) throw err;
  console.log('PM2 version retrieved');
});

// Test daemon connection
pm2.ping((err) => {
  if (err) {
    console.log('PM2 daemon not responding');
  } else {
    console.log('PM2 daemon is running');
  }
});

// Update PM2 daemon
pm2.update((err) => {
  if (err) throw err;
  console.log('PM2 daemon updated');
});

Common Configuration Keys

PM2 supports various configuration keys that can be managed through the configuration API:

pm2_home - PM2 home directory path
log-date-format - Timestamp format for logs
max-memory-restart - Global memory restart threshold
kill-timeout - Global kill timeout in milliseconds
restart-delay - Global restart delay in milliseconds
daemon - Daemon mode setting
instances - Default number of instances
exec-mode - Default execution mode
watch - Default file watching setting
ignore-watch - Default ignore patterns for watching
merge-logs - Default log merging setting
log-type - Log output type
log-rotate - Log rotation settings

Ecosystem Files

PM2 supports ecosystem files (JavaScript or JSON) for complex configuration management:

JavaScript Ecosystem File (ecosystem.config.js)

module.exports = {
  apps: [{
    name: 'app',
    script: './app.js',
    instances: 'max',
    exec_mode: 'cluster',
    env: {
      NODE_ENV: 'development'
    },
    env_production: {
      NODE_ENV: 'production',
      PORT: 3000
    }
  }],
  deploy: {
    production: {
      user: 'ubuntu',
      host: ['192.168.1.100'],
      ref: 'origin/master',
      repo: 'git@github.com:username/repository.git',
      path: '/var/www/production',
      'post-deploy': 'npm install && pm2 reload ecosystem.config.js --env production'
    }
  }
};

JSON Ecosystem File (ecosystem.json)

{
  "apps": [{
    "name": "worker",
    "script": "worker.js",
    "instances": 2,
    "exec_mode": "fork",
    "watch": true,
    "ignore_watch": ["node_modules", "logs"],
    "max_memory_restart": "1G",
    "env": {
      "NODE_ENV": "development"
    },
    "env_production": {
      "NODE_ENV": "production"
    }
  }]
}

Core Types

interface InstallOptions {
  /** Install from tarball */
  tarball?: boolean;
  /** Perform installation (default: true) */
  install?: boolean;
  /** Docker mode */
  docker?: boolean;
  /** Use v1 API */
  v1?: boolean;
  /** Safe mode installation */
  safe?: boolean | number;
}

interface ServeOptions {
  /** Single Page Application mode */
  spa?: boolean;
  /** Basic authentication username */
  basic_auth_username?: string;
  /** Basic authentication password */
  basic_auth_password?: string;
  /** Monitor URL path */
  monitor?: string;
}

Install with Tessl CLI