Development Server Setup with PM2 and Hot Reloading

Overview

This document provides a comprehensive guide to setting up a robust development server with PM2 process management, hot reloading, and Playwright integration for the Waves and Algorithms project.

Key Features

Robust PM2 Configuration: Advanced process management with port handling
Hot Reloading: File watching and automatic browser refresh
Playwright Integration: End-to-end testing capabilities
Development Scripts: Comprehensive npm scripts for development workflow
Error Handling: Graceful error handling and logging
Automatic Chrome Launching: Automatically opens Chrome when files are modified or preview is requested

Installation and Setup

1. Install Dependencies

# Install core dependencies
npm install

# Install Playwright browsers
npx playwright install

2. Development Server Configuration

The development server (dev-server.js) provides:

Static File Serving: Serves files from public_html/ directory
Hot Reloading: Watches for file changes and triggers browser refresh
Directory Listing: Auto-generates directory indexes
Error Handling: Graceful 404 and 500 error pages
Health Check: /health endpoint for monitoring
WebSocket Support: Hot reload communication

3. PM2 Configuration

The PM2 configuration (ecosystem.config.js) includes:

Port Management: Automatic port detection and fallback
Process Management: Advanced process monitoring and restart
Logging: Comprehensive logging with rotation
Environment Variables: Development and production environments
Health Checks: Automated health monitoring
Graceful Shutdown: Proper process termination

4. Playwright Integration

The test launcher (test-launcher.js) provides:

Test Execution: Automated Playwright test execution
Server Health Check: Verifies development server is running
Configuration Management: Dynamic test configuration
Error Handling: Comprehensive error reporting

Usage

Development Mode

# Start development server with PM2
npm run dev:pm2

# Start development server directly
npm run dev

# Monitor server status
npm run pm2:monit

# View logs
npm run pm2:logs

Testing

# Run Playwright tests
npm run test:e2e

# Run tests with UI mode
npm run test:e2e:ui

# Update test snapshots
npm run test:e2e:update

PM2 Management

# Start server
npm run pm2:start

# Stop server
npm run pm2:stop

# Restart server
npm run pm2:restart

# Delete server
npm run pm2:delete

# Save current process list
npm run pm2:save

# Restore saved process list
npm run pm2:resurrect

Browser Automation

Automatic Chrome Launching

The system automatically launches Chrome when:

Development server starts - Chrome opens automatically to the main page
Files are modified - Chrome refreshes automatically and brings window to front
Tests are executed - Chrome launches for Playwright test automation
Health checks are performed - Chrome verifies server functionality
User requests preview - When user asks to preview a file, Chrome opens it automatically

Preview Feature

When you complete a new feature on an HTML file and request a preview:

Automatic Detection: The system detects the file change
Chrome Launch: Chrome automatically opens with the updated file
Real-time Updates: Any further changes automatically refresh the browser
Window Focus: Chrome window is brought to the front so you can see changes immediately
No Manual Intervention: No need to manually open Chrome, refresh pages, or find the window

Smart Window Management

The system includes intelligent window management:

Existing Chrome Instance: If Chrome is already open, it brings the window to the front
Multiple Tabs: Maintains existing tabs and opens new ones when needed
Window State: Preserves window position and size when possible
Focus Management: Ensures the Chrome window has focus for immediate viewing

Development Workflow

Start Server: npm run dev:pm2 - Chrome opens automatically
Edit File: Make changes to any HTML/CSS/JS file
Auto Refresh: Chrome automatically refreshes and comes to front
See Changes: Immediate visual feedback without any manual intervention
Continue Development: Make more changes and see updates instantly

Usage Examples

# Start development server - Chrome opens automatically
npm run dev:pm2

# Modify a file - Chrome refreshes and comes to front
echo "console.log('test');" >> public_html/script.js

# Request preview of specific file - Chrome opens and comes to front
curl -X POST http://localhost:8000/preview?file=index.html

# Edit HTML file - Chrome refreshes and brings window to front
echo "New Feature
" >> public_html/index.html

API Reference

Development Server API

Endpoints

GET / - Serve main page

GET /health - Health check endpoint

GET /__hot-reload - Hot reload endpoint

GET /path/to/file - Serve static file

POST /preview?file= - Automatically open file in Chrome for preview

GET /preview - List available files for preview

WebSocket Events

connected - Client connected
file-change - File changed
file-add - File added
file-remove - File removed

PM2 API

Process Management

start - Start process
stop - Stop process
restart - Restart process
reload - Graceful reload
delete - Delete process

Monitoring

monit - Monitor processes
logs - View logs
status - Check status
info - Process information

Playwright API

Test Execution

test:e2e - Run tests
test:e2e:ui - Run tests with UI
test:e2e:update - Update snapshots

Configuration

testDir - Test directory
baseURL - Base URL
retries - Retry count
browser - Browser type

Troubleshooting

Common Issues

1. Port Already in Use

# Check port usage
lsof -i :8000

# Kill process using port
kill -9

2. PM2 Process Issues

# Reset PM2
npm run pm2:kill
npm run pm2:start

3. File Watching Issues

# Check file permissions
ls -la public_html/

# Restart file watcher
npm run pm2:restart

4. Playwright Issues

# Reinstall browsers
npx playwright install --force

# Clear test cache
rm -rf tests/results/

Debug Mode

Enable debug mode for troubleshooting:

# Enable debug logging
export DEBUG=*
npm run dev:pm2

Support

For support and questions:

Check the troubleshooting section
Review the logs for error messages
Check the GitHub issues
Contact the development team

Waves and Algorithms Development Server Setup Guide