Local dev server management — start, stop, clean restart, fix cache corruption, port conflicts. Use this skill whenever the dev server needs launching or is misbehaving.
.next cache corruption (vendor-chunks ENOENT, 404 on static chunks)Always prefer a clean start to avoid stale cache issues:
# 1. Kill any existing process on port 3030
lsof -ti:3030 | xargs kill -9 2>/dev/null
# 2. Clean .next cache (prevents stale vendor-chunk errors)
rm -rf .next
# 3. Start dev server in background
npx next dev -p 3030 &
# 4. Wait for ready, then verify
sleep 8 && curl -s -o /dev/null -w "%{http_code}" http://localhost:3030
First page load after clean start takes ~20-30s to compile. This is normal.
Only use when you know the cache is fine (small code edits):
lsof -ti:3030 | xargs kill -9 2>/dev/null
npx next dev -p 3030 &
For long sessions where server should auto-restart on crash:
# Start
pm2 start npm --name "empathy-ledger" -- run dev
# Restart
pm2 restart empathy-ledger
# Clean restart (fixes cache issues)
pm2 stop empathy-ledger && rm -rf .next && pm2 start empathy-ledger
# Logs
pm2 logs empathy-ledger --lines 50
# Stop
pm2 stop empathy-ledger
# Cache corruption — clean restart fixes it
lsof -ti:3030 | xargs kill -9 2>/dev/null
rm -rf .next
npx next dev -p 3030 &
lsof -ti:3030 | xargs kill -9 2>/dev/null
npx next dev -p 3030 &
/auth/signinrm -rf .next
# Restart server
After starting the server, verify:
curl -s -o /dev/null -w "%{http_code}" http://localhost:3030 returns 200 or 307deployment-workflow — Production deploymentsupabase-connection — Database setup
