Terminal Port Manager

A Next.js component for managing terminal ports and processes. This package provides an easy way to check port availability and manage processes using those ports.

Installation

npm install terminal-port-manager
# or
yarn add terminal-port-manager
# or
bun add terminal-port-manager

Features

• Automatic port checking
• Process management
• Built-in Next.js page component
• TypeScript support
• Zero configuration required

How It Works

Detect Project Structure:
    The findTargetStructure function checks for the existence of directories like app/api, src/app/api, pages/api, and src/pages/api.
    It returns the first matching structure or defaults to app router.

Process Files:
    For API routes, it generates the file dynamically from the content string.
    For page components, it copies the file from the package to the appropriate directory.

Create Folders if Missing:
    If the required directories don’t exist (e.g., app/api), the script creates them using fs.ensureDir().

Run During Installation:
    The script is executed automatically as part of the postinstall lifecycle hook in package.json.

Usage

Automatic Page (Zero Configuration)

The package includes a pre-built page component. After installation, you can access it at:

/terminal-port-manager

This page will show a list of common ports (3000, 3001, 3002, 8080) and their status.

Manual Component Usage

import { TerminalPortManager } from 'terminal-port-manager';

function MyComponent() {
  return (
    <TerminalPortManager
      port={3000}
      onPortClear={() => console.log('Port is clear')}
      onPortBusy={(pid) => console.log(`Process ${pid} is using the port`)}
    />
  );
}

Types

interface TerminalPortManagerProps {
  port: number;
  onPortClear?: () => void;
  onPortBusy?: (pid: number) => void;
}

Project Structure

terminal-port-manager/
├── api/
│   └── terminal-port-manager-execute-commands/
│       └── route.ts               # API endpoint for executing commands
├── src/
│   ├── app/
│   │   └── terminal-port-manager/
│   │       └── page.tsx           # Auto-included page component
│   ├── components/
│   │   └── TerminalPortManager.tsx # Main component
│   ├── utils/
│   │   └── portUtils.ts           # Port management utilities
│   └── index.ts                   # Main entry point
├── dist/                          # Built files
│   ├── index.js                   # CommonJS bundle
│   ├── index.mjs                  # ES Modules bundle
│   └── index.d.ts                 # TypeScript declarations
├── package.json
└── tsconfig.json

Requirements

• Node.js >= 14
• Next.js >= 13
• React >= 18

API Reference

TerminalPortManager Component

Props:

• port (number): The port number to monitor
• onPortClear (optional function): Callback when port becomes available
• onPortBusy (optional function): Callback when port is in use, receives process ID

Utility Functions

// Check if a port is in use
async function checkPort(port: number): Promise<number | null>

// Kill a process by its ID
async function killProcess(pid: number): Promise<void>

License

MIT