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

Module Management

Name: tessl/npm-pm2
Author: tessl

PM2 module system for extending functionality with plugins and add-ons. Provides installation, packaging, publishing, and lifecycle management for PM2 modules including development tools and production enhancements.

Capabilities

Module Installation and Management

Install, uninstall, and manage PM2 modules from the PM2 registry or custom sources.

/**
 * Install PM2 module
 * @param module_name - Name of module to install from PM2 registry
 * @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;

/**
 * Delete module completely (including files)
 * @param module_name - Name of module to delete
 * @param callback - Called when deletion completes
 */
function deleteModule(module_name: string, callback?: (err: Error) => void): void;

Usage Examples:

const pm2 = require('pm2');

// Install popular PM2 modules
pm2.install('pm2-logrotate', (err) => {
  if (err) throw err;
  console.log('Log rotation module installed');
});

pm2.install('pm2-server-monit', (err) => {
  if (err) throw err;
  console.log('Server monitoring module installed');
});

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

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

// Completely delete module
pm2.deleteModule('old-module', (err) => {
  if (err) throw err;
  console.log('Module deleted completely');
});

Module Development

Tools for developing, packaging, and publishing PM2 modules.

/**
 * Generate module template/boilerplate
 * @param app_name - Name for the new module
 * @param callback - Called when template is generated
 */
function generateModuleSample(app_name: string, callback?: (err: Error) => void): void;

/**
 * Package module for distribution
 * @param module_path - Path to module directory
 * @param callback - Called when packaging completes
 */
function package(module_path: string, callback?: (err: Error) => void): void;

/**
 * Publish module to PM2 registry
 * @param folder - Module folder path
 * @param options - Publishing options
 * @param callback - Called when publishing completes
 */
function publish(folder: string, options?: PublishOptions, callback?: (err: Error) => void): void;

Usage Examples:

// Generate new module template
pm2.generateModuleSample('my-awesome-module', (err) => {
  if (err) throw err;
  console.log('Module template created in ./my-awesome-module/');
});

// Package module for distribution
pm2.package('./my-module', (err) => {
  if (err) throw err;
  console.log('Module packaged successfully');
});

// Publish module to registry
pm2.publish('./my-module', {
  public: true,
  force: false
}, (err) => {
  if (err) throw err;
  console.log('Module published to PM2 registry');
});

Module Lifecycle

Manage module lifecycle and startup operations.

/**
 * Launch all installed modules
 * @param CLI - PM2 CLI instance
 * @param callback - Called when all modules are launched
 */
function launchAll(CLI: any, callback?: (err: Error) => void): void;

Usage Examples:

// Launch all installed modules (typically used internally)
pm2.launchAll(pm2, (err) => {
  if (err) throw err;
  console.log('All modules launched');
});

Popular PM2 Modules

Official Modules

pm2-logrotate - Automatic log rotation for PM2 processes
pm2-server-monit - Server monitoring and alerting
pm2-auto-pull - Automatic git pull and reload
pm2-slack - Slack notifications for PM2 events
pm2-webshell - Web-based shell interface
pm2-health - Health check and monitoring

Installation Examples

// Essential production modules
const productionModules = [
  'pm2-logrotate',
  'pm2-server-monit', 
  'pm2-slack'
];

pm2.connect((err) => {
  if (err) throw err;
  
  productionModules.forEach(module => {
    pm2.install(module, (err) => {
      if (err) console.error(`Failed to install ${module}:`, err);
      else console.log(`${module} installed successfully`);
    });
  });
});

Development Workflow

// Complete module development workflow
pm2.connect((err) => {
  if (err) throw err;
  
  // 1. Generate module template
  pm2.generateModuleSample('my-pm2-plugin', (err) => {
    if (err) throw err;
    
    console.log('1. Module template created');
    console.log('2. Edit ./my-pm2-plugin/app.js to implement functionality');
    console.log('3. Test your module locally');
    
    // 4. Package when ready
    pm2.package('./my-pm2-plugin', (err) => {
      if (err) throw err;
      
      console.log('4. Module packaged');
      
      // 5. Publish to registry
      pm2.publish('./my-pm2-plugin', { public: true }, (err) => {
        if (err) throw err;
        console.log('5. Module published to PM2 registry');
        pm2.disconnect();
      });
    });
  });
});

Module Configuration

Module Ecosystem File

Modules can be configured using ecosystem files:

// ecosystem.config.js
module.exports = {
  apps: [{
    name: 'my-app',
    script: 'app.js'
  }],
  modules: [{
    name: 'pm2-logrotate',
    options: {
      max_size: '10M',
      retain: 30,
      compress: true
    }
  }, {
    name: 'pm2-server-monit',
    options: {
      drive: true,
      network: true,
      port: 8080
    }
  }]
};

Module Environment Variables

Many modules support configuration through environment variables:

# pm2-logrotate configuration
PM2_LOGROTATE_MAX_SIZE=10M
PM2_LOGROTATE_RETAIN=30
PM2_LOGROTATE_COMPRESS=true

# pm2-server-monit configuration  
PM2_SERVER_MONIT_PORT=8080
PM2_SERVER_MONIT_REFRESH=5000

Core Types

interface InstallOptions {
  /** Install from tarball instead of registry */
  tarball?: boolean;
  /** Perform installation (default: true) */
  install?: boolean;
  /** Docker mode installation */
  docker?: boolean;
  /** Use PM2 v1 API compatibility */
  v1?: boolean;
  /** Safe mode installation with retry attempts */
  safe?: boolean | number;
}

interface PublishOptions {
  /** Make module public in registry */
  public?: boolean;
  /** Force publish even if version exists */
  force?: boolean;
  /** Include development dependencies */
  dev?: boolean;
}

Module Development Guidelines

Module Structure

my-pm2-module/
├── package.json          # NPM package configuration
├── app.js               # Main module entry point
├── probe.js             # Custom metrics (optional)
├── README.md            # Module documentation
└── ecosystem.config.js  # Module configuration

Basic Module Template (app.js)

const pmx = require('@pm2/io');

// Initialize module
const conf = pmx.initModule({
  widget: {
    type: 'generic',
    logo: 'https://app.keymetrics.io/img/logo/keymetrics-300.png',
    theme: ['#111111', '#1B2228', '#31C2F1', '#807C7C'],
    el: {
      probes: true,
      actions: true
    }
  }
}, (err, conf) => {
  if (err) return console.error(err);

  // Module configuration from PM2
  console.log('Module configuration:', conf);
  
  // Add custom metrics
  const probe = pmx.probe();
  const metric = probe.metric({
    name: 'Custom Metric',
    value: 0
  });

  // Add custom actions
  pmx.action('test action', (reply) => {
    reply({ success: true, message: 'Action executed' });
  });

  // Module logic here
  setInterval(() => {
    metric.set(Math.random() * 100);
  }, 1000);
});

Install with Tessl CLI