pm2-restart-hook

A simple and lightweight PM2 module that creates a parent-child dependency between your applications, automatically restarting child processes when their designated parent application is restarted

Features

pm2-restart-hook offers several key features for better process management:

• Dependency Management: Easily create a parent-child relationship between any PM2-managed applications
• Automated Cascading Restarts: When a parent app restarts, all its children are automatically restarted
• Highly Configurable: Customize behavior using environment variables, with sensible defaults for zero-configuration use
• Lightweight & Simple: No external dependencies beyond PM2 itself

Requirements

• PM2 v5.0.0+

Installation

You can install the module directly from NPM:

pm2 install pm2-restart-hook

How It Works

The hook identifies the parent-child relationship using a simple environment variable. When a parent application restarts, the hook finds all other applications that have their PM2_PARENT_APP environment variable set to the parent's name and restarts them

Usage Example

The best way to manage parent-child applications is with an ecosystem.config.js file

1. Create your applications. For this example, we'll use a placeholder script dummy-app.js
2. Define the relationship in ecosystem.config.js:

// ecosystem.config.js

module.exports = {
  apps: [
    // 1. The Parent Application
    {
      name: 'api-server',
      script: 'api.js',
      // Common reasons for automated restarts
      max_memory_restart: '500M',
      cron_restart: '0 2 * * *', // Restart every day at 2 AM
    },

    // 2. Child Worker #1
    {
      name: 'email-worker',
      script: 'worker.js',
      env: {
        // This links the worker to its parent.
        // The value MUST match the parent's 'name'.
        PM2_PARENT_APP: 'api-server',
      },
    },

    // 3. Child Worker #2
    {
      name: 'analytics-worker',
      script: 'worker.js',
      env: {
        PM2_PARENT_APP: 'api-server',
      },
    },
  ],
};

3. Start your applications:

pm2 start ecosystem.config.js

Now, whenever api-server restarts (whether from its cron schedule, memory limit, or a manual command), email-worker and analytics-worker will be gracefully restarted one after another

Configuration

You can configure the hook's behavior by setting variables on the module itself using the pm2 set command

Environment Variable	Description	Default
PARENT_ENV_KEY	The environment variable key used to identify the parent app	PM2_PARENT_APP
IGNORE_MANUAL_RESTARTS	If set to true, manual restarts (pm2 restart <app>) will be ignored	true
CHILD_RESTART_DELAY_MS	The delay in milliseconds between restarting each child process to prevent system overload	200

Example of setting a configuration variable:

# Make the hook to not ignore manual restarts
pm2 set pm2-restart-hook:IGNORE_MANUAL_RESTARTS false

# Change the restart delay to 1 second
pm2 set pm2-restart-hook:CHILD_RESTART_DELAY_MS 1000

Thanks To

• You for viewing or using this project
• The Keymetrics team for creating and maintaining the powerful PM2 process manager

License

This project is licensed under the MIT License.