/add-bg-scripts

add-bg-scripts.md

Add Background Process Management Scripts

This prompt helps you add background process management scripts to any Node.js project with a development server (Expo, Next.js, Vite, etc.).

Instructions

1. Analyze the project to determine:

   • Package manager (npm, yarn, pnpm, bun)
   • Dev server command (start, dev, serve, etc.)
   • Default port number
   • Framework type (for cache-clearing flags)

2. Check existing scripts in package.json to understand the project's conventions

3. Add the background scripts with proper customization

Process

Step 1: Examine package.json

# Read package.json to identify:
# - Existing scripts (especially dev/start commands)
# - Dependencies (to identify framework)
# - Package manager from lock files

Step 2: Detect Configuration

• Framework Detection:

  • Next.js: Look for next in dependencies
  • Vite: Look for vite in dependencies
  • Expo: Look for expo in dependencies
  • Create React App: Look for react-scripts
  • Custom webpack: Look for webpack-dev-server

• Port Detection:

  • Check for port in existing scripts
  • Look for .env files with PORT variable
  • Check framework config files (vite.config.js, next.config.js, etc.)
  • Use framework defaults if not found

• Dev Command Detection:

  • Look for dev, start, serve in scripts
  • Identify the primary development command

Step 3: Generate Customized Scripts

Based on detection, add these scripts with proper values:

{
  "scripts": {
    // ... existing scripts ...
    "bg:start": "mkdir -p tmp && kill -9 $(lsof -ti:PORT) 2>/dev/null; nohup PACKAGE_MANAGER DEV_COMMAND > tmp/output.log 2>&1 & echo $! > tmp/server.pid",
    "bg:start-clear-cache": "mkdir -p tmp && kill -9 $(lsof -ti:PORT) 2>/dev/null; nohup PACKAGE_MANAGER DEV_COMMAND CACHE_FLAG > tmp/output.log 2>&1 & echo $! > tmp/server.pid",
    "bg:stop": "[ -f tmp/server.pid ] && kill $(cat tmp/server.pid) || echo 'No server running'",
    "bg:logs": "tail -50 tmp/output.log",
    "bg:logs-watch": "tail -f tmp/output.log",
    "bg:status": "[ -f tmp/server.pid ] && ps -p $(cat tmp/server.pid) >/dev/null && echo 'Server running (PID: '$(cat tmp/server.pid)')' || echo 'Server not running'",
    "bg:restart": "PACKAGE_MANAGER run bg:stop && sleep 2 && PACKAGE_MANAGER run bg:start",
    "bg:clean": "rm -rf tmp/"
  }
}

Step 4: Framework-Specific Customizations

Common Replacements:

• PORT: Actual port number (3000, 4200, 5173, 8080, etc.)
• PACKAGE_MANAGER: npm, yarn, pnpm, or bun
• DEV_COMMAND: The actual command (e.g., run dev, start, run serve)
• CACHE_FLAG: Framework-specific cache clearing flag

Cache Clearing Flags by Framework:

• Expo: -- --clear
• Next.js: -- --turbo
• Vite: (no cache flag needed)
• Create React App: (no cache flag needed)

Step 5: Add to .gitignore

Ensure tmp/ is in .gitignore:

# Add to .gitignore if not already present
echo "tmp/" >> .gitignore

Default Port Numbers by Framework

• Next.js: 3000
• Create React App: 3000
• Vite: 5173
• Vue CLI: 8080
• Angular: 4200
• Expo: 8081
• Gatsby: 8000
• Nuxt: 3000
• SvelteKit: 5173
• Remix: 3000

Implementation Steps

1. Read package.json to understand the project structure
2. Detect package manager from lock files:
   • package-lock.json → npm
   • yarn.lock → yarn
   • pnpm-lock.yaml → pnpm
   • bun.lockb → bun
3. Identify dev command from scripts section
4. Determine port from:
   • Command line args in scripts
   • Environment variables
   • Config files
   • Framework defaults
5. Add customized scripts to package.json
6. Update .gitignore to exclude tmp/
7. Test the scripts to ensure they work

Example Detection Logic

// Pseudo-code for detection
const packageJson = readPackageJson();
const dependencies = { ...packageJson.dependencies, ...packageJson.devDependencies };

// Detect framework
let framework = 'unknown';
if (dependencies.next) framework = 'nextjs';
else if (dependencies.vite) framework = 'vite';
else if (dependencies.expo) framework = 'expo';
else if (dependencies['react-scripts']) framework = 'cra';
// ... etc

// Detect dev command
const scripts = packageJson.scripts || {};
let devCommand = scripts.dev ? 'dev' : scripts.start ? 'start' : 'dev';

// Detect package manager
let packageManager = 'npm';
if (fileExists('yarn.lock')) packageManager = 'yarn';
else if (fileExists('pnpm-lock.yaml')) packageManager = 'pnpm';
else if (fileExists('bun.lockb')) packageManager = 'bun';

// Get default port for framework
const defaultPorts = {
  nextjs: 3000,
  vite: 5173,
  expo: 8081,
  cra: 3000,
  // ... etc
};
const port = defaultPorts[framework] || 3000;

After Adding Scripts

Users can then:

• npm run bg:start - Start server in background
• npm run bg:logs - Show last 50 lines of logs
• npm run bg:logs-watch - Watch logs in real-time
• npm run bg:status - Check if server is running
• npm run bg:stop - Stop the server
• npm run bg:restart - Restart the server
• npm run bg:clean - Clean up tmp directory

Notes

• Scripts automatically handle port conflicts by killing existing processes
• All output is logged to tmp/output.log for debugging
• The tmp/ directory is created automatically
• Process ID is stored in tmp/server.pid for management