@tyoshii/react-port-switcher

A lightweight React component that lets you quickly switch between running dev servers on localhost. Perfect for microservice or monorepo setups where multiple services run on different ports.

Development only. This component only renders on localhost / 127.0.0.1. Do not use in production environments.

Features

• One-click navigation to any registered port
• Remembers manually added ports and visit history
• Alive-check on popover open (with 5s cache)
• Fully customizable theme (colors via CSS variables)
• Fixed or inline positioning
• Only renders on localhost — zero overhead in production

Browser Support

Uses color-mix() for theming:

• Chrome 111+
• Safari 16.2+
• Firefox 113+

Install

npm install @tyoshii/react-port-switcher

Quick Start

import { PortSwitcher } from '@tyoshii/react-port-switcher';
import '@tyoshii/react-port-switcher/styles.css';

function App() {
  return <PortSwitcher position="bottom-right" />;
}

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | position | 'top-left' \| 'top-center' \| 'top-right' \| 'bottom-left' \| 'bottom-center' \| 'bottom-right' | — | Fixed position on screen. Omit for inline placement. | | className | string | — | Additional CSS classes for the wrapper. | | theme | { textColor?, backgroundColor?, accentColor?, mutedColor? } | — | Color customization via CSS variables. | | icon | ReactNode | Monitor icon | Custom trigger icon. | | onNavigate | (url: string, port: string) => void | Opens new tab | Custom navigation handler. | | labels | { title?, empty?, portPlaceholder? } | — | UI text overrides for i18n. |

Theme Example

<PortSwitcher
  position="bottom-right"
  theme={{
    textColor: '#fff',
    backgroundColor: '#1e1b4b',
    accentColor: '#facc15',
    mutedColor: '#a5b4fc',
  }}
/>

Peer Dependencies

• react >= 18
• react-dom >= 18

License

MIT