0
# Module Management
1

2
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.
3

4
## Capabilities
5

6
### Module Installation and Management
7

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

10
```javascript { .api }
11
/**
12
 * Install PM2 module
13
 * @param module_name - Name of module to install from PM2 registry
14
 * @param options - Installation options
15
 * @param callback - Called when installation completes
16
 */
17
function install(module_name: string, options?: InstallOptions, callback?: (err: Error) => void): void;
18

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

26
/**
27
 * Delete module completely (including files)
28
 * @param module_name - Name of module to delete
29
 * @param callback - Called when deletion completes
30
 */
31
function deleteModule(module_name: string, callback?: (err: Error) => void): void;
32
```
33

34
**Usage Examples:**
35

36
```javascript
37
const pm2 = require('pm2');
38

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

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

50
// Install with options
51
pm2.install('pm2-auto-pull', {
52
  safe: true,
53
  install: true
54
}, (err) => {
55
  if (err) throw err;
56
  console.log('Auto-pull module installed in safe mode');
57
});
58

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

65
// Completely delete module
66
pm2.deleteModule('old-module', (err) => {
67
  if (err) throw err;
68
  console.log('Module deleted completely');
69
});
70
```
71

72
### Module Development
73

74
Tools for developing, packaging, and publishing PM2 modules.
75

76
```javascript { .api }
77
/**
78
 * Generate module template/boilerplate
79
 * @param app_name - Name for the new module
80
 * @param callback - Called when template is generated
81
 */
82
function generateModuleSample(app_name: string, callback?: (err: Error) => void): void;
83

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

91
/**
92
 * Publish module to PM2 registry
93
 * @param folder - Module folder path
94
 * @param options - Publishing options
95
 * @param callback - Called when publishing completes
96
 */
97
function publish(folder: string, options?: PublishOptions, callback?: (err: Error) => void): void;
98
```
99

100
**Usage Examples:**
101

102
```javascript
103
// Generate new module template
104
pm2.generateModuleSample('my-awesome-module', (err) => {
105
  if (err) throw err;
106
  console.log('Module template created in ./my-awesome-module/');
107
});
108

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

115
// Publish module to registry
116
pm2.publish('./my-module', {
117
  public: true,
118
  force: false
119
}, (err) => {
120
  if (err) throw err;
121
  console.log('Module published to PM2 registry');
122
});
123
```
124

125
### Module Lifecycle
126

127
Manage module lifecycle and startup operations.
128

129
```javascript { .api }
130
/**
131
 * Launch all installed modules
132
 * @param CLI - PM2 CLI instance
133
 * @param callback - Called when all modules are launched
134
 */
135
function launchAll(CLI: any, callback?: (err: Error) => void): void;
136
```
137

138
**Usage Examples:**
139

140
```javascript
141
// Launch all installed modules (typically used internally)
142
pm2.launchAll(pm2, (err) => {
143
  if (err) throw err;
144
  console.log('All modules launched');
145
});
146
```
147

148
## Popular PM2 Modules
149

150
### Official Modules
151

152
- **pm2-logrotate** - Automatic log rotation for PM2 processes
153
- **pm2-server-monit** - Server monitoring and alerting
154
- **pm2-auto-pull** - Automatic git pull and reload
155
- **pm2-slack** - Slack notifications for PM2 events
156
- **pm2-webshell** - Web-based shell interface
157
- **pm2-health** - Health check and monitoring
158

159
### Installation Examples
160

161
```javascript
162
// Essential production modules
163
const productionModules = [
164
  'pm2-logrotate',
165
  'pm2-server-monit', 
166
  'pm2-slack'
167
];
168

169
pm2.connect((err) => {
170
  if (err) throw err;
171
  
172
  productionModules.forEach(module => {
173
    pm2.install(module, (err) => {
174
      if (err) console.error(`Failed to install ${module}:`, err);
175
      else console.log(`${module} installed successfully`);
176
    });
177
  });
178
});
179
```
180

181
### Development Workflow
182

183
```javascript
184
// Complete module development workflow
185
pm2.connect((err) => {
186
  if (err) throw err;
187
  
188
  // 1. Generate module template
189
  pm2.generateModuleSample('my-pm2-plugin', (err) => {
190
    if (err) throw err;
191
    
192
    console.log('1. Module template created');
193
    console.log('2. Edit ./my-pm2-plugin/app.js to implement functionality');
194
    console.log('3. Test your module locally');
195
    
196
    // 4. Package when ready
197
    pm2.package('./my-pm2-plugin', (err) => {
198
      if (err) throw err;
199
      
200
      console.log('4. Module packaged');
201
      
202
      // 5. Publish to registry
203
      pm2.publish('./my-pm2-plugin', { public: true }, (err) => {
204
        if (err) throw err;
205
        console.log('5. Module published to PM2 registry');
206
        pm2.disconnect();
207
      });
208
    });
209
  });
210
});
211
```
212

213
## Module Configuration
214

215
### Module Ecosystem File
216

217
Modules can be configured using ecosystem files:
218

219
```javascript
220
// ecosystem.config.js
221
module.exports = {
222
  apps: [{
223
    name: 'my-app',
224
    script: 'app.js'
225
  }],
226
  modules: [{
227
    name: 'pm2-logrotate',
228
    options: {
229
      max_size: '10M',
230
      retain: 30,
231
      compress: true
232
    }
233
  }, {
234
    name: 'pm2-server-monit',
235
    options: {
236
      drive: true,
237
      network: true,
238
      port: 8080
239
    }
240
  }]
241
};
242
```
243

244
### Module Environment Variables
245

246
Many modules support configuration through environment variables:
247

248
```bash
249
# pm2-logrotate configuration
250
PM2_LOGROTATE_MAX_SIZE=10M
251
PM2_LOGROTATE_RETAIN=30
252
PM2_LOGROTATE_COMPRESS=true
253

254
# pm2-server-monit configuration  
255
PM2_SERVER_MONIT_PORT=8080
256
PM2_SERVER_MONIT_REFRESH=5000
257
```
258

259
## Core Types
260

261
```javascript { .api }
262
interface InstallOptions {
263
  /** Install from tarball instead of registry */
264
  tarball?: boolean;
265
  /** Perform installation (default: true) */
266
  install?: boolean;
267
  /** Docker mode installation */
268
  docker?: boolean;
269
  /** Use PM2 v1 API compatibility */
270
  v1?: boolean;
271
  /** Safe mode installation with retry attempts */
272
  safe?: boolean | number;
273
}
274

275
interface PublishOptions {
276
  /** Make module public in registry */
277
  public?: boolean;
278
  /** Force publish even if version exists */
279
  force?: boolean;
280
  /** Include development dependencies */
281
  dev?: boolean;
282
}
283
```
284

285
## Module Development Guidelines
286

287
### Module Structure
288

289
```
290
my-pm2-module/
291
├── package.json          # NPM package configuration
292
├── app.js               # Main module entry point
293
├── probe.js             # Custom metrics (optional)
294
├── README.md            # Module documentation
295
└── ecosystem.config.js  # Module configuration
296
```
297

298
### Basic Module Template (app.js)
299

300
```javascript
301
const pmx = require('@pm2/io');
302

303
// Initialize module
304
const conf = pmx.initModule({
305
  widget: {
306
    type: 'generic',
307
    logo: 'https://app.keymetrics.io/img/logo/keymetrics-300.png',
308
    theme: ['#111111', '#1B2228', '#31C2F1', '#807C7C'],
309
    el: {
310
      probes: true,
311
      actions: true
312
    }
313
  }
314
}, (err, conf) => {
315
  if (err) return console.error(err);
316

317
  // Module configuration from PM2
318
  console.log('Module configuration:', conf);
319
  
320
  // Add custom metrics
321
  const probe = pmx.probe();
322
  const metric = probe.metric({
323
    name: 'Custom Metric',
324
    value: 0
325
  });
326

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

332
  // Module logic here
333
  setInterval(() => {
334
    metric.set(Math.random() * 100);
335
  }, 1000);
336
});
337
```