vscode-port-monitor-config

name

vscode-port-monitor-config

description

This skill should be used when configuring VS Code Port Monitor extension for development server monitoring. Use when the user asks to "set up port monitoring for Vite", "monitor my dev server ports", "configure port monitor for Next.js", "track which ports are running", "set up multi-port monitoring", "monitor frontend and backend ports", or "check port status in VS Code". Provides ready-to-use configuration templates for Vite (5173), Next.js (3000), and microservices architectures with troubleshooting guidance.

VS Code Port Monitor Configuration

Configure the VS Code Port Monitor extension to monitor development server ports in real-time with visual status indicators in your status bar.

Extension: dkurokawa.vscode-port-monitor

Core Concepts

Port Monitor Features

• 🔍 Real-time monitoring - Live status bar display
• 🏷️ Intelligent configuration - Supports arrays, ranges, well-known ports
• 🛑 Process management - Kill processes using ports
• 🎨 Customizable display - Icons, colors, positioning
• 📊 Multiple groups - Organize ports by service/project

Status Icons

• 🟢 = Port is in use (service running)
• ⚪️ = Port is free (service stopped)

---

Configuration Workflow

Step 1: Create Configuration File

Add configuration to .vscode/settings.json:

{
  "portMonitor.hosts": {
    "GroupName": {
      "port": "label",
      "__CONFIG": { ... }
    }
  }
}

Step 2: Choose a Template

Select from common scenarios (see examples/ directory):

Scenario	Template File	Ports
Vite basic	vite-basic.json	5173 (dev)
Vite with preview	vite-with-preview.json	5173 (dev), 4173 (preview)
Full stack	fullstack.json	5173, 4173, 3200
Next.js	nextjs.json	3000 (app), 3001 (api)
Microservices	microservices.json	Multiple groups

Step 3: Apply Configuration

1. Copy template content to .vscode/settings.json
2. Customize port numbers and labels for your project
3. Save file - Port Monitor will auto-reload

---

Quick Start Examples

Example 1: Vite Project

{
  "portMonitor.hosts": {
    "Development": {
      "5173": "dev",
      "__CONFIG": {
        "compact": true,
        "bgcolor": "blue",
        "show_title": true
      }
    }
  },
  "portMonitor.statusIcons": {
    "inUse": "🟢 ",
    "free": "⚪️ "
  }
}

Display: Development: [🟢 dev:5173]

Example 2: Microservices

{
  "portMonitor.hosts": {
    "Frontend": {
      "3000": "react",
      "__CONFIG": { "compact": true, "bgcolor": "blue", "show_title": true }
    },
    "Backend": {
      "3001": "api",
      "5432": "postgres",
      "__CONFIG": { "compact": true, "bgcolor": "yellow", "show_title": true }
    }
  }
}

Display: Frontend: [🟢 react:3000] Backend: [🟢 api:3001 | 🟢 postgres:5432]

---

Best Practices

✅ Do

• Use descriptive labels: "5173": "dev" not "5173": "5173"
• Add space after emojis: "🟢 " for better readability
• Group related ports: Frontend, Backend, Database
• Use compact mode for cleaner status bar
• Set reasonable refresh interval (3000-5000ms)

❌ Don't

• Reverse port-label format: "dev": 5173 ❌
• Use empty group names
• Set refresh interval too low (<1000ms)
• Monitor too many ports (>10 per group)

---

Common Issues

Port Monitor Not Showing

1. Check extension is installed: code --list-extensions | grep port-monitor
2. Verify .vscode/settings.json syntax
3. Reload VS Code: Cmd+Shift+P → "Reload Window"

Configuration Errors

Check port-label format is correct:

// ✅ Correct
{"5173": "dev"}

// ❌ Wrong
{"dev": 5173}

For more troubleshooting, see references/troubleshooting.md

---

Reference Materials

• Configuration Options: references/configuration-options.md - Detailed option reference
• Troubleshooting: references/troubleshooting.md - Common issues and solutions
• Integrations: references/integrations.md - Tool-specific configurations
• Advanced Config: references/advanced-config.md - Pattern matching, custom emojis
• Examples: examples/ - Ready-to-use JSON configurations

---

Workflow Summary

1. Choose template from examples/ directory based on your stack
2. Copy to .vscode/settings.json
3. Customize port numbers and labels
4. Save and verify status bar display
5. Troubleshoot if needed using references/troubleshooting.md

Port Monitor will automatically detect running services and update the status bar in real-time.