home / skills / petekp / claude-code-setup / dev-server

dev-server skill

safe

This skill starts development servers with intelligent port management, auto-detects environment, handles conflicts, and opens the browser for a seamless local

npx playbooks add skill petekp/claude-code-setup --skill dev-server

Review the files below or copy the command above to add this skill to your agents.

Files (2)

SKILL.md

2.4 KB

---
name: dev-server
description: Start development servers with intelligent port management. Use when asked to "start the dev server", "run dev", "start development", "launch the server", "spin up the app", "get this running", "boot the frontend", or any request to run a local development server. Handles port conflicts, detects project type, cleans up stale processes, and opens the browser automatically.
license: MIT
metadata:
  author: petekp
  version: "0.1.0"
---

# Dev Server

## Workflow

1. **Check ports** - Run `scripts/check_ports.sh` to scan common dev ports
2. **Resolve conflicts**:
   - **Same project**: Use `--kill-if-same` to kill without asking
   - **Different project**: Ask user before killing or use alternate port
3. **Detect environment** - Check for docker-compose.yml, monorepo structure, or package.json
4. **Start server** - Use detected package manager with `--open` flag; add `--port <n>` if needed

## Port Script

```bash
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.json` or `packages/app/package.json` (Turborepo/Nx pattern)
- Root package.json with workspace `dev` script 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.

Overview

This skill starts local development servers with intelligent port management and environment detection. It handles port conflicts, cleans up stale processes when safe, picks the appropriate package manager, and opens the browser automatically. The goal is to get your app running with minimal fuss and safe defaults.

How this skill works

The skill first scans common dev ports to detect running processes and determines if they belong to the same project by comparing working directories. It then resolves conflicts by killing same-project processes automatically or prompting/choosing an alternate port for different projects. Next it detects the project environment (docker-compose, monorepo layout, framework) and selects the proper start command and package manager. Finally it launches the server with the correct port/open flags and falls back to opening the browser via a URL when needed.

When to use it

When you want to "start the dev server", "run dev", or "launch the server" locally.
When a port conflict prevents your app from starting and you need safe conflict resolution.
When working in monorepos or projects with multiple package managers and you want automatic detection.
When you prefer automatic browser opening after the dev server becomes available.
When you need to spin up a Docker-based web service and get a recommendation for docker compose.

Best practices

Run the skill from the project root to enable accurate ownership detection.
Prefer --kill-if-same for non-interactive workflows to safely replace stale same-project processes.
Use project-specific scripts (dev) in package.json to ensure consistent startup behavior in monorepos.
Commit lockfiles so package manager detection (bun/pnpm/yarn/npm) is reliable.
Choose an explicit port with --port when sharing machines to avoid surprises.

Example use cases

You run "start the dev server" and the skill finds port 3000 in use by an old instance; it kills it and reboots the app.
In a monorepo, it detects apps/web/package.json and runs the correct dev script for that subproject.
On a Docker project with docker-compose.yml, it suggests using docker compose up instead of npm run.
A colleague accidentally started a different project on your port; the skill prompts and selects an alternate port.
Your framework doesn’t honor --open; the skill starts the server and opens http://localhost:PORT in your browser.

FAQ

How does it decide whether a running process belongs to this project?

It compares the running process working directory to the current directory and treats parent/child paths as the same project.

What if my framework uses a nonstandard port flag?

The skill knows common exceptions (e.g., CRA uses PORT env var, Gatsby uses -p) and applies appropriate flags or env variables.

Can it force-kill a process?

Yes. Use the force option to kill any process, but by default it prompts when the process appears to belong to a different project.