Complete Guide to Running npm start Scripts with PM2

Introduction

In modern Node.js application development, process management is a critical aspect of ensuring application stability. Many developers use npm start to launch applications during development, but running Node.js directly in production environments can introduce single points of failure. PM2, as a powerful process manager, effectively addresses these issues. This article provides an in-depth analysis of how to use PM2 to run npm start scripts and discusses related best practices.

Basic Methods for Running npm start with PM2

According to the best answer from the Q&A data, PM2 supports running npm start scripts directly. The specific command is as follows:

pm2 start npm -- start

In this command, npm serves as the script to execute, while -- start is passed as an argument to npm. It is important to note that the space after -- is crucial, ensuring that start is correctly recognized as an npm argument rather than a PM2 option.

To better distinguish and manage multiple processes, the --name option can be used to name the process:

pm2 start npm --name "my-app" -- start

This way, in PM2's process list, the process will be displayed as "my-app", facilitating monitoring and management.

Using Configuration Files to Run npm start

In addition to the command-line approach, PM2 also supports process management via JSON configuration files. Referencing the supplementary answer from the Q&A data, the following configuration file can be created:

{
    "apps": [
        {
            "name": "my-app",
            "script": "npm",
            "args": "start"
        }
    ]
}

After saving as my-app-pm2.json, run the following command to start the application:

pm2 start my-app-pm2.json

The configuration file approach is particularly suitable for complex application scenarios, such as when the application is located in a subdirectory. The working directory can be specified using the cwd attribute:

{
    "apps": [
        {
            "name": "my-nested-app",
            "cwd": "./nested-app",
            "script": "npm",
            "args": "start"
        }
    ]
}

This way, PM2 will execute the npm start command in the ./nested-app directory.

Risks of Running Node.js Directly and Advantages of PM2

The reference article points out that running Node.js directly in production environments carries significant risks. For example, when unhandled errors occur in the application, the entire process may crash, leading to service unavailability. Below is a simple Express server example:

const express = require('express');
const app = express();
const fs = require('fs');

app.get('/', (req, res) => {
    res.send('Hello World');
});

app.get('/read', (req, res) => {
    // Attempt to read a non-existent file
    fs.readFile('/nonexistent/file', (err, data) => {
        if (err) throw err; // Unhandled error will crash the process
        res.send(data);
    });
});

app.listen(3000, () => {
    console.log('Server running on port 3000');
});

If this application is run directly using node index.js, accessing the /read endpoint will throw an error due to the non-existent file, causing the entire application to stop serving. All subsequent requests will fail until the application is manually restarted.

PM2 addresses these issues through the following mechanisms:

• Automatic Restart: When the application crashes, PM2 automatically restarts the process, ensuring high availability.
• Process Monitoring: PM2 continuously monitors process status and takes appropriate actions upon anomalies.
• Log Management: Application logs can be easily viewed via the pm2 logs command, facilitating troubleshooting.

Advanced Features of PM2

PM2 not only provides basic process management but also supports various advanced features to further enhance application reliability and performance.

Cluster Mode

PM2 can run multiple application instances in cluster mode to achieve load balancing. Set the instances parameter in the configuration file:

{
    "apps": [
        {
            "name": "my-app",
            "script": "npm",
            "args": "start",
            "instances": 4,
            "exec_mode": "cluster"
        }
    ]
}

This configuration will start 4 application instances, with PM2 automatically distributing requests among them. If the exact number of CPU cores is unknown, it can be set to "max":

"instances": "max"

PM2 will automatically detect the number of CPU cores and start a corresponding number of instances, fully utilizing system resources.

File Watching and Automatic Restart

In development environments, PM2 can monitor file changes and automatically restart the application, similar to the functionality of nodemon:

pm2 start npm --name "my-app" --watch -- start

Or set via configuration file:

{
    "apps": [
        {
            "name": "my-app",
            "script": "npm",
            "args": "start",
            "watch": true
        }
    ]
}

Alternative Solutions and Considerations

Although PM2 is a popular Node.js process management solution, alternative approaches may need to be considered in certain scenarios.

Containerized Deployment

In container orchestration platforms like Kubernetes, Node.js applications can be run directly, with the platform responsible for monitoring and restarting containers. For example, in Azure App Service, even without PM2, applications are automatically recovered by the platform after crashes.

System-Level Monitoring

For Linux environments, system-level service managers like systemd can be used to run Node.js applications. This approach does not rely on Node.js's own process management and provides lower-level control.

Error Handling and Testing

Regardless of the process management solution used, robust error handling and comprehensive testing are fundamental to ensuring application stability. Unhandled exceptions should be avoided, and test cases should cover critical functionalities.

Practical Application Example

The following is a complete example demonstrating how to use PM2 to run an npm start script in a real project.

First, ensure PM2 is installed globally:

npm install -g pm2

Create a PM2 configuration file ecosystem.config.js:

module.exports = {
    apps: [{
        name: 'my-express-app',
        script: 'npm',
        args: 'start',
        instances: 'max',
        exec_mode: 'cluster',
        watch: false,
        env: {
            NODE_ENV: 'production'
        }
    }]
};

Start the application:

pm2 start ecosystem.config.js

Check process status:

pm2 status

View application logs:

pm2 logs my-express-app

Stop the application:

pm2 stop my-express-app

Delete process record:

pm2 delete my-express-app

Conclusion

PM2 offers a powerful and flexible solution for running npm start scripts, whether through command-line or configuration files. It not only addresses the single points of failure associated with running Node.js directly but also provides advanced features such as cluster mode and file watching. In practical projects, the appropriate solution should be selected based on specific requirements and deployment environments, combined with robust error handling and testing practices to ensure application stability and reliability.