0
# Portfinder
1
2
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.
3
4
## Package Information
5
6
- **Package Name**: portfinder
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install portfinder`
10
11
## Core Imports
12
13
```javascript
14
const portfinder = require('portfinder');
15
```
16
17
For ES modules:
18
```javascript
19
import portfinder from 'portfinder';
20
```
21
22
## Basic Usage
23
24
```javascript
25
const portfinder = require('portfinder');
26
27
// Find a free port (callback style)
28
portfinder.getPort(function (err, port) {
29
if (err) throw err;
30
console.log('Free port:', port); // e.g., 8000
31
});
32
33
// Find a free port (Promise style)
34
portfinder.getPortPromise()
35
.then((port) => {
36
console.log('Free port:', port);
37
})
38
.catch((err) => {
39
console.error('Error finding port:', err);
40
});
41
42
// Find multiple ports
43
portfinder.getPortsPromise(3)
44
.then((ports) => {
45
console.log('Free ports:', ports); // e.g., [8000, 8001, 8002]
46
});
47
48
// Find port in specific range
49
portfinder.getPort({
50
port: 3000, // minimum port
51
stopPort: 3333 // maximum port
52
}, function(err, port) {
53
console.log('Port between 3000-3333:', port);
54
});
55
```
56
57
## Architecture
58
59
Portfinder is built around several key components:
60
61
- **Port Discovery Engine**: Tests port availability by attempting to bind to each port using Node.js native networking modules
62
- **Range Scanning**: Configurable port range scanning with global defaults and per-call overrides
63
- **Host Resolution**: Automatic detection of all local network interfaces plus support for custom hosts
64
- **Error Handling**: Robust handling of common network errors (EADDRINUSE, EACCES, EADDRNOTAVAIL)
65
- **Dual API**: Both callback and Promise-based interfaces for all operations
66
67
## Capabilities
68
69
### Port Configuration
70
71
Global configuration settings for port discovery operations including base port, highest port, and base socket path settings.
72
73
```javascript { .api }
74
// Configuration properties
75
portfinder.basePort: number; // Default: 8000
76
portfinder.highestPort: number; // Default: 65535
77
portfinder.basePath: string; // Default: '/tmp/portfinder'
78
79
// Configuration functions
80
function setBasePort(port: number): void;
81
function setHighestPort(port: number): void;
82
function setBasePath(path: string): void;
83
```
84
85
[Port Configuration](./port-configuration.md)
86
87
### Port Finding
88
89
Core port discovery functionality for finding single or multiple available ports with configurable host and range options.
90
91
```javascript { .api }
92
// Single port discovery
93
function getPort(options?: PortFinderOptions): Promise<number>;
94
function getPort(callback: (err: Error, port: number) => void): void;
95
function getPort(options: PortFinderOptions, callback: (err: Error, port: number) => void): void;
96
97
// Multiple port discovery
98
function getPorts(count: number, options?: PortFinderOptions): Promise<number[]>;
99
function getPorts(count: number, callback: (err: Error, ports: number[]) => void): void;
100
function getPorts(count: number, options: PortFinderOptions, callback: (err: Error, ports: number[]) => void): void;
101
102
interface PortFinderOptions {
103
host?: string; // Host to find available port on
104
port?: number; // Minimum port (takes precedence over basePort)
105
startPort?: number; // Search start port (equals port when not provided)
106
stopPort?: number; // Maximum port
107
}
108
```
109
110
[Port Finding](./port-finding.md)
111
112
### Socket Finding
113
114
Unix socket path discovery for finding available socket file paths with configurable directory and permission settings.
115
116
```javascript { .api }
117
// Socket discovery
118
function getSocket(options?: SocketFinderOptions): Promise<string>;
119
function getSocket(callback: (err: Error, socket: string) => void): void;
120
function getSocket(options: SocketFinderOptions, callback: (err: Error, socket: string) => void): void;
121
122
interface SocketFinderOptions {
123
path?: string; // Path to the socket file to create (defaults to ${basePath}.sock)
124
mod?: number; // Mode to use when creating folder for socket if it doesn't exist
125
}
126
```
127
128
[Socket Finding](./socket-finding.md)
129
130
## Types
131
132
```javascript { .api }
133
// Callback type definitions
134
type PortfinderCallback = (err: Error, port: number) => void;
135
type SocketfinderCallback = (err: Error, socket: string) => void;
136
137
// Options interfaces
138
interface PortFinderOptions {
139
host?: string; // Host to find available port on
140
startPort?: number; // Search start port (equals port when not provided)
141
port?: number; // Minimum port (takes precedence over basePort)
142
stopPort?: number; // Maximum port
143
}
144
145
interface SocketFinderOptions {
146
mod?: number; // Mode to use when creating folder for socket if it doesn't exist
147
path?: string; // Path to the socket file to create
148
}
149
```
150
151
## Error Handling
152
153
Portfinder handles several categories of errors:
154
155
- **No ports available**: "No open ports available" when search range is exhausted
156
- **Invalid ranges**: "Provided options.stopPort(X) is less than options.port(Y)" for invalid port ranges
157
- **Invalid ports**: "Provided options.port(X) is less than 0, which are cannot be bound." for negative ports
158
- **Host binding failures**: "Provided host X could NOT be bound. Please provide a different host address or hostname" for invalid hosts
159
- **Network errors**: Standard Node.js network errors (EADDRINUSE, EACCES, EADDRNOTAVAIL) are handled automatically