@banyudu/plasmo-dev-wrapper

A wrapper for plasmo dev that monitors for fatal errors and exits to trigger PM2 auto-restart. This solves the issue where Plasmo's dev server stays running in a broken state after compilation errors, preventing PM2 from restarting.

Problem

When using plasmo dev with PM2, compilation errors (like missing files after moving them) don't cause the process to exit. The server stays running in a broken state, and PM2 can't auto-restart it.

Solution

This wrapper:

• Monitors plasmo dev output for fatal error patterns
• Exits after detecting consecutive errors (default: 3 errors with 5s debounce)
• Resets error count when builds succeed
• Triggers PM2's auto-restart functionality

Installation

pnpm add -D @banyudu/plasmo-dev-wrapper

Or use directly with npx (no installation needed):

npx @banyudu/plasmo-dev-wrapper

Usage

With PM2 (Recommended)

1. Add script to package.json:

{
  "scripts": {
    "dev:pm2": "plasmo-dev-wrapper"
  }
}

2. Update ecosystem.config.js:

{
  name: "my-extension",
  script: "pnpm",
  args: "dev:pm2",
  interpreter: "none",
  autorestart: true,
  max_restarts: 10,
  min_uptime: "10s",
  restart_delay: 2000,
  watch: false
}

3. Start with PM2:

pm2 start ecosystem.config.js

Standalone

# Default usage (runs "plasmo dev")
plasmo-dev-wrapper

# With verbose logging
plasmo-dev-wrapper --verbose

# Custom threshold and debounce
plasmo-dev-wrapper --threshold 5 --debounce 10000

# Custom command
plasmo-dev-wrapper --command "npm run dev"

CLI Options

| Option | Description | Default | |--------|-------------|---------| | -v, --verbose | Enable verbose logging | false | | -t, --threshold <number> | Error threshold before exit | 3 | | -d, --debounce <ms> | Debounce time between errors | 5000 | | -c, --command <cmd> | Command to run | plasmo dev | | -h, --help | Show help message | - |

Error Patterns

The wrapper monitors for these fatal error patterns:

• ENOENT: no such file or directory
• Module not found
• Cannot find module
• Failed to resolve

Success pattern (resets error count):

• Extension re-packaged

How It Works

1. Spawns plasmo dev as a child process
2. Monitors stdout/stderr for error patterns
3. Counts consecutive errors (with debounce)
4. Exits with code 1 when threshold is reached
5. PM2 detects the exit and restarts the process
6. Resets error count when successful build is detected

Verification

1. Start with PM2: pm2 start ecosystem.config.js
2. Trigger an error (move/delete a source file)
3. Watch logs: pm2 logs
4. Verify wrapper exits after threshold
5. Verify PM2 auto-restarts
6. Restore the file and confirm recovery

Example Output

[plasmo-dev-wrapper] Starting plasmo dev...
[plasmo-dev-wrapper] Fatal error detected (1/3)
[plasmo-dev-wrapper] Fatal error detected (2/3)
[plasmo-dev-wrapper] Fatal error detected (3/3)
[plasmo-dev-wrapper] Error threshold reached - exiting to trigger PM2 restart

License

MIT

Author

Yudu Ban [email protected]