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

• Copy template content to .vscode/settings.json

• Customize port numbers and labels for your project

• 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

• Check extension is installed: code --list-extensions | grep port-monitor

• Verify .vscode/settings.json syntax

• 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

• Choose template from examples/ directory based on your stack

• Copy to .vscode/settings.json

• Customize port numbers and labels

• Save and verify status bar display

• Troubleshoot if needed using references/troubleshooting.md

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