or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

cli-commands.mdconfiguration.mddocker-integration.mdindex.mdmodule-management.mdmonitoring.mdprocess-management.mdtypescript-definitions.mdversion-control.md
tile.json

tessl/npm-pm2

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

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/pm2@6.0.x

To install, run

npx @tessl/cli install tessl/npm-pm2@6.0.0

index.mddocs/

PM2

PM2 is a production process manager for Node.js applications with a built-in load balancer. It provides daemon-like process management, built-in load balancing, zero-downtime reloads, cluster mode for horizontal scaling, comprehensive monitoring, automatic crash recovery, and container integration. PM2 is essential for production Node.js application lifecycle management with enterprise-grade reliability and performance optimization capabilities.

Package Information

  • Package Name: pm2
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install pm2 -g (global) or npm install pm2 (local)
  • CLI Usage: Global installation provides pm2, pm2-dev, pm2-docker, pm2-runtime commands
  • Programmatic Usage: Require as a Node.js module for API access

Core Imports

For programmatic use:

const pm2 = require('pm2');

For TypeScript:

import * as pm2 from 'pm2';
import { StartOptions, ProcessDescription } from 'pm2';

Custom PM2 instance:

const PM2 = require('pm2').custom;
const customPm2 = new PM2({
  pm2_home: '/custom/path',
  daemon_mode: false
});

Basic Usage

Programmatic API

const pm2 = require('pm2');

// Connect to PM2 daemon
pm2.connect((err) => {
  if (err) {
    console.error(err);
    process.exit(2);
  }

  // Start a process
  pm2.start({
    script: 'app.js',
    name: 'my-app',
    instances: 'max',
    exec_mode: 'cluster'
  }, (err, apps) => {
    if (err) {
      console.error(err);
      return pm2.disconnect();
    }

    // List all processes
    pm2.list((err, processes) => {
      console.log(processes);
      pm2.disconnect();
    });
  });
});

CLI Usage

# Start an application
pm2 start app.js --name "my-app" -i max

# List all processes
pm2 list

# Monitor processes
pm2 monit

# Stop all processes
pm2 stop all

# Reload with zero downtime
pm2 reload all

# Save current process list
pm2 save

# Resurrect saved processes
pm2 resurrect

Architecture

PM2 is built around several key components:

  • Daemon (God): Background process managing all applications
  • Client API: Programmatic interface for process management operations
  • CLI Interface: Command-line tool providing full functionality access
  • Process Containers: Wrapper components handling different execution modes (fork, cluster)
  • Load Balancer: Built-in HTTP load balancing for cluster mode
  • Monitoring System: Real-time process metrics and log management
  • Configuration System: Persistent settings and ecosystem file support
  • Module System: Plugin architecture for extending functionality

Capabilities

Process Management

Core process lifecycle operations including starting, stopping, restarting, and deleting managed processes. Supports multiple execution modes and clustering.

// Connection management
function connect(callback: (err: Error) => void): void;
function connect(noDaemonMode: boolean, callback: (err: Error) => void): void;
function disconnect(): void;

// Process lifecycle
function start(options: StartOptions, callback: (err: Error, proc: Proc) => void): void;
function stop(process: string | number, callback: (err: Error, proc: Proc) => void): void;
function restart(process: string | number, callback: (err: Error, proc: Proc) => void): void;
function reload(process: string | number, callback: (err: Error, proc: Proc) => void): void;
function delete(process: string | number, callback: (err: Error, proc: Proc) => void): void;

Process Management

Monitoring and Information

Process monitoring, system metrics collection, and detailed process information retrieval. Includes real-time monitoring interfaces and performance profiling.

function list(callback: (err: Error, processes: ProcessDescription[]) => void): void;
function describe(process: string | number, callback: (err: Error, description: ProcessDescription[]) => void): void;
function launchSysMonitoring(callback?: (err: Error) => void): void;
function profile(type: 'cpu' | 'mem', time?: number, callback?: (err: Error) => void): void;

Monitoring and Information

Configuration Management

PM2 configuration management including getting, setting, and persisting configuration values. Supports both runtime and persistent configuration.

function get(key?: string, callback?: (err: Error) => void): void;
function set(key: string, value: any, callback?: (err: Error) => void): void;
function multiset(values: string, callback?: (err: Error) => void): void;
function unset(key: string, callback?: (err: Error) => void): void;

Configuration Management

CLI Commands

Comprehensive command-line interface providing 68 commands for process management, monitoring, configuration, and system integration.

# Core process management
pm2 start <script|config> [options]
pm2 stop <id|name|all>
pm2 restart <id|name|all>
pm2 reload <id|name|all>
pm2 delete <id|name|all>

# Information and monitoring
pm2 list
pm2 describe <id|name>
pm2 monit

CLI Commands

Module Management

PM2 module system for extending functionality with plugins and add-ons. Install, develop, package, and publish PM2 modules for production enhancements.

function install(module_name: string, options?: InstallOptions, callback?: (err: Error) => void): void;
function uninstall(module_name: string, callback?: (err: Error) => void): void;
function generateModuleSample(app_name: string, callback?: (err: Error) => void): void;
function package(module_path: string, callback?: (err: Error) => void): void;
function publish(folder: string, options?: PublishOptions, callback?: (err: Error) => void): void;

Module Management

Version Control Integration

Git-based deployment and version management for production applications. Automated deployment, rollback, and source code management.

function pullAndRestart(process_name: string, callback?: (err: Error, result: any) => void): void;
function pullAndReload(process_name: string, callback?: (err: Error, result: any) => void): void;
function pullCommitId(process_name: string, commit_id: string, callback?: (err: Error, result: any) => void): void;
function backward(process_name: string, callback?: (err: Error, result: any) => void): void;
function forward(process_name: string, callback?: (err: Error, result: any) => void): void;

Version Control Integration

Docker Integration

Container-optimized runtime modes, Dockerfile generation, and production-ready containerization with proper signal handling.

function generateDockerfile(script: string, options?: DockerOptions): string;
function dockerMode(script: string, options?: DockerOptions, mode?: string): any;
pm2-runtime <script|config> [options]
pm2-docker <script|config> [options]

Docker Integration

Core Types

interface StartOptions {
  name?: string;
  script?: string;
  args?: string | string[];
  cwd?: string;
  env?: { [key: string]: string };
  instances?: number;
  exec_mode?: string;
  watch?: boolean | string[];
  merge_logs?: boolean;
  output?: string;
  error?: string;
  log_date_format?: string;
  autorestart?: boolean;
  max_restarts?: number;
  max_memory_restart?: number | string;
  kill_timeout?: number;
  restart_delay?: number;
  wait_ready?: boolean;
  namespace?: string;
}

interface ProcessDescription {
  name?: string;
  pid?: number;
  pm_id?: number;
  monit?: {
    memory?: number;
    cpu?: number;
  };
  pm2_env?: {
    pm_cwd?: string;
    pm_out_log_path?: string;
    pm_err_log_path?: string;
    status?: ProcessStatus;
    instances?: number | 'max';
    pm_uptime?: number;
    restart_time?: number;
    unstable_restarts?: number;
  };
}

type ProcessStatus = 'online' | 'stopping' | 'stopped' | 'launching' | 'errored' | 'one-launch-status' | 'waiting_restart';

Complete TypeScript Definitions