or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.mdport-configuration.mdport-finding.mdsocket-finding.md
tile.json

tessl/npm-portfinder

A simple tool to find an open port on the current machine

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/portfinder@1.0.x

To install, run

npx @tessl/cli install tessl/npm-portfinder@1.0.0

index.mddocs/

Portfinder

Portfinder is a lightweight Node.js utility library for finding available network ports and Unix socket paths on the local machine. It provides both callback and Promise-based APIs for asynchronously discovering free ports within configurable ranges, making it ideal for development servers, test environments, and applications requiring dynamic port allocation.

Package Information

  • Package Name: portfinder
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install portfinder

Core Imports

const portfinder = require('portfinder');

For ES modules:

import portfinder from 'portfinder';

Basic Usage

const portfinder = require('portfinder');

// Find a free port (callback style)
portfinder.getPort(function (err, port) {
  if (err) throw err;
  console.log('Free port:', port); // e.g., 8000
});

// Find a free port (Promise style)
portfinder.getPortPromise()
  .then((port) => {
    console.log('Free port:', port);
  })
  .catch((err) => {
    console.error('Error finding port:', err);
  });

// Find multiple ports
portfinder.getPortsPromise(3)
  .then((ports) => {
    console.log('Free ports:', ports); // e.g., [8000, 8001, 8002]
  });

// Find port in specific range
portfinder.getPort({
  port: 3000,    // minimum port
  stopPort: 3333 // maximum port
}, function(err, port) {
  console.log('Port between 3000-3333:', port);
});

Architecture

Portfinder is built around several key components:

  • Port Discovery Engine: Tests port availability by attempting to bind to each port using Node.js native networking modules
  • Range Scanning: Configurable port range scanning with global defaults and per-call overrides
  • Host Resolution: Automatic detection of all local network interfaces plus support for custom hosts
  • Error Handling: Robust handling of common network errors (EADDRINUSE, EACCES, EADDRNOTAVAIL)
  • Dual API: Both callback and Promise-based interfaces for all operations

Capabilities

Port Configuration

Global configuration settings for port discovery operations including base port, highest port, and base socket path settings.

// Configuration properties
portfinder.basePort: number;      // Default: 8000
portfinder.highestPort: number;   // Default: 65535
portfinder.basePath: string;      // Default: '/tmp/portfinder'

// Configuration functions
function setBasePort(port: number): void;
function setHighestPort(port: number): void;
function setBasePath(path: string): void;

Port Configuration

Port Finding

Core port discovery functionality for finding single or multiple available ports with configurable host and range options.

// Single port discovery
function getPort(options?: PortFinderOptions): Promise<number>;
function getPort(callback: (err: Error, port: number) => void): void;
function getPort(options: PortFinderOptions, callback: (err: Error, port: number) => void): void;

// Multiple port discovery  
function getPorts(count: number, options?: PortFinderOptions): Promise<number[]>;
function getPorts(count: number, callback: (err: Error, ports: number[]) => void): void;
function getPorts(count: number, options: PortFinderOptions, callback: (err: Error, ports: number[]) => void): void;

interface PortFinderOptions {
  host?: string;      // Host to find available port on
  port?: number;      // Minimum port (takes precedence over basePort)
  startPort?: number; // Search start port (equals port when not provided)
  stopPort?: number;  // Maximum port
}

Port Finding

Socket Finding

Unix socket path discovery for finding available socket file paths with configurable directory and permission settings.

// Socket discovery
function getSocket(options?: SocketFinderOptions): Promise<string>;
function getSocket(callback: (err: Error, socket: string) => void): void;
function getSocket(options: SocketFinderOptions, callback: (err: Error, socket: string) => void): void;

interface SocketFinderOptions {
  path?: string; // Path to the socket file to create (defaults to ${basePath}.sock)
  mod?: number;  // Mode to use when creating folder for socket if it doesn't exist
}

Socket Finding

Types

// Callback type definitions
type PortfinderCallback = (err: Error, port: number) => void;
type SocketfinderCallback = (err: Error, socket: string) => void;

// Options interfaces
interface PortFinderOptions {
  host?: string;      // Host to find available port on
  startPort?: number; // Search start port (equals port when not provided)
  port?: number;      // Minimum port (takes precedence over basePort)
  stopPort?: number;  // Maximum port
}

interface SocketFinderOptions {
  mod?: number;   // Mode to use when creating folder for socket if it doesn't exist
  path?: string;  // Path to the socket file to create
}

Error Handling

Portfinder handles several categories of errors:

  • No ports available: "No open ports available" when search range is exhausted
  • Invalid ranges: "Provided options.stopPort(X) is less than options.port(Y)" for invalid port ranges
  • Invalid ports: "Provided options.port(X) is less than 0, which are cannot be bound." for negative ports
  • Host binding failures: "Provided host X could NOT be bound. Please provide a different host address or hostname" for invalid hosts
  • Network errors: Standard Node.js network errors (EADDRINUSE, EACCES, EADDRNOTAVAIL) are handled automatically