PM2 Ecosystem Generator
Build a copy-paste-ready PM2 ecosystem.config.js with cluster mode, env vars, and watch options.
Client-side only — nothing leaves your browser
No variables — block will be omitted from output.
module.exports = {
apps: [
{
name: 'my-app',
script: './server.js',
exec_mode: 'fork',
watch: false,
env: {
NODE_ENV: 'development',
},
env_production: {
NODE_ENV: 'production',
},
}
],
};
Save this as ecosystem.config.js in your project root, then run pm2 start ecosystem.config.js.
What is a PM2 Ecosystem File?
A PM2 ecosystem file (typically named ecosystem.config.js) is a single configuration file that defines one or more Node.js applications PM2 should manage. Instead of passing flags on the command line every time you start an app, you declare your app name, entry script, instance count, environment variables, log paths, and restart policies in one place. PM2 then loads them with pm2 start ecosystem.config.js, making your process configuration repeatable, version-controlled, and consistent across staging and production.
Common Ecosystem Fields
| Field | Purpose |
|---|---|
| name | Display name shown in pm2 list / pm2 monit |
| script | Path to your entry file (e.g. ./server.js or npm) |
| cwd | Working directory PM2 will cd into before running |
| instances | Number of processes (use 'max' for one per CPU) |
| exec_mode | fork (single process) or cluster (load-balanced) |
| watch | Restart on file changes — leave off in production |
| autorestart | Auto-restart on crash (default: true) |
| max_memory_restart | Restart if RAM exceeds limit (e.g. 500M, 1G) |
| out_file | Path for stdout log output |
| error_file | Path for stderr log output |
| env / env_production / env_staging | Environment variables loaded with --env <name> |
Useful PM2 Commands
| Command | What it does |
|---|---|
| pm2 start ecosystem.config.js | Start all apps defined in the file |
| pm2 start ecosystem.config.js --env production | Start using env_production variables |
| pm2 start ecosystem.config.js --only my-app | Start only one named app |
| pm2 reload ecosystem.config.js | Zero-downtime reload (cluster mode) |
| pm2 restart ecosystem.config.js | Restart all apps from the file |
| pm2 stop ecosystem.config.js | Stop all apps defined in the file |
| pm2 delete ecosystem.config.js | Remove all apps from PM2 |
| pm2 save | Persist current process list across reboots |
| pm2 startup | Generate and configure startup script for your OS |
Frequently Asked Questions
Where should I put my pm2 ecosystem.config.js file?
Put ecosystem.config.js in the root of your project — the same directory you run pm2 from. PM2 looks for the file in the current working directory by default, so 'pm2 start ecosystem.config.js' must be run from that folder. You can also pass an absolute path: 'pm2 start /var/www/my-app/ecosystem.config.js'. Commit the file to git so your config is reproducible across servers, but keep secrets out of it — load those from a separate .env file or your shell environment.
What is the difference between fork and cluster mode in PM2?
Fork mode runs your script as a single Node.js process — simple, predictable, and works for any script (Node, Python, bash). Cluster mode uses Node's built-in cluster module to spawn multiple worker processes that share the same port via the OS load balancer, giving you near-linear scaling across CPU cores. Use cluster mode for stateless HTTP servers (Express, Fastify, Next.js) where you want to use all CPUs. Use fork mode for workers, cron-style scripts, anything stateful, or non-Node binaries. Cluster mode requires your app to actually be a Node.js HTTP server — it cannot cluster Python or shell scripts.
How do I start PM2 with the ecosystem file?
From the directory containing the file, run 'pm2 start ecosystem.config.js'. To use a specific environment, add the --env flag: 'pm2 start ecosystem.config.js --env production' will merge the env_production variables. To start only one app from a multi-app file, use --only: 'pm2 start ecosystem.config.js --only api'. After starting, run 'pm2 save' so the process list survives reboots, and 'pm2 startup' once to install the systemd/launchd service that auto-loads on boot.
Why does PM2 say ecosystem.config.js not found?
This error usually means one of three things: (1) you're running pm2 from a different directory than where the file lives — cd into the project root or pass the absolute path, (2) the file extension does not match — if your project's package.json has "type": "module", Node treats .js as ESM and PM2's CommonJS loader fails, so rename to ecosystem.config.cjs, or (3) the filename is slightly off (PM2 expects ecosystem.config.js, ecosystem.config.cjs, or ecosystem.config.json — not pm2.config.js or app.config.js). Run 'ls ecosystem.config*' to confirm the file is actually there.
Should I use .js, .cjs, or .mjs for my PM2 ecosystem file?
Use .js when your project is CommonJS (no "type": "module" in package.json) — this is the default and what most tutorials show. Use .cjs when your project's package.json sets "type": "module" but you still want CommonJS export syntax (module.exports = {...}) — PM2's loader expects CommonJS, so .cjs forces that interpretation regardless of the package type. PM2 also supports .mjs and .json, but .mjs requires ESM-style export default {...} syntax. The safest cross-project choice today is .cjs with module.exports — it works in both CommonJS and ESM projects without any package.json changes.
Related Tools
Need to manage SSH connections?
SSH Workbench lets you connect, browse files, and manage servers visually.
Try SSH Workbench Free