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):

vite-basic.json

vite-with-preview.json

fullstack.json

nextjs.json

microservices.json

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.