Dev Server
Workflow
- Check ports - Run
scripts/check_ports.shto scan common dev ports - Resolve conflicts:
- Same project: Use --kill-if-same to kill without asking - Different project: Ask user before killing or use alternate port
- Detect environment - Check for docker-compose.yml, monorepo structure, or package.json
- Start server - Use detected package manager with
--openflag; add--port <n>if needed
Port Script
scripts/check_ports.sh # Scan ports, show which project each belongs to
scripts/check_ports.sh 3000 # Check specific port with project info
scripts/check_ports.sh --find 3000 # Find first available port
scripts/check_ports.sh --kill-if-same 3000 # Kill only if same project (safe)
scripts/check_ports.sh --kill 3000 # Force kill (ask user first if different project)The script detects project ownership by comparing the process's working directory to the current directory. "Same project" means the process was started from this directory or a parent/child of it.
Environment Detection
Docker projects: If docker-compose.yml exists with a web/app service, suggest docker compose up instead.
Monorepos: Check if current directory has package.json with dev script. If not, look for:
apps/web/package.jsonorpackages/app/package.json(Turborepo/Nx pattern)- Root package.json with workspace
devscript that delegates
Package manager: Detect from lockfile (bun.lockb → bun, pnpm-lock.yaml → pnpm, yarn.lock → yarn, otherwise npm).
Framework Notes
Most frameworks support --open and --port flags. Exceptions:
| Framework | Default Port | Notes |
|---|---|---|
| Create React App | 3000 | Uses PORT=3001 env var instead of --port |
| Gatsby | 8000 | Uses -p instead of --port |
| Remix | 3000 | --port works in dev mode |
When --open doesn't work, fall back to open http://localhost:PORT after server starts.