portfinder

What is portfinder?

The portfinder npm package is a utility for getting a port number that is guaranteed to be free on the current machine. It is useful for running servers on dynamically assigned ports to avoid conflicts.

What are portfinder's main functionalities?

Get an available port

This feature allows you to find an available port on the machine. The `getPort` function takes a callback that provides the port number.

const portfinder = require('portfinder');

portfinder.getPort((err, port) => {
  if (err) {
    throw err;
  }
  console.log('Available port found:', port);
});

Set the base port

Before calling `getPort`, you can set the `basePort` property to tell portfinder to start searching for a free port from a certain number.

const portfinder = require('portfinder');

portfinder.basePort = 3000;
portfinder.getPort((err, port) => {
  if (err) {
    throw err;
  }
  console.log('Available port found:', port);
});

Set the range of ports to search

You can specify a range of ports for portfinder to search within by providing an options object with `port` and `stopPort` properties.

const portfinder = require('portfinder');

portfinder.getPort({
  port: 3000, // minimum port
  stopPort: 3333 // maximum port
}, (err, port) => {
  if (err) {
    throw err;
  }
  console.log('Available port found:', port);
});

Other packages similar to portfinder

get-port

Similar to portfinder, get-port is a package that helps you get an available TCP port to listen on. Unlike portfinder, get-port returns a Promise and supports async/await syntax, which can be more convenient in modern Node.js applications.

detect-port

Detect-port is another package that checks for an available port on your machine. It is similar to portfinder but also allows you to check if a specific port is available and returns an alternative if it's not, which can be useful for suggesting the next available port.

README

node-portfinder

Installation

You can install portfinder using a package manager like npm, yarn, or bun:

npm install portfinder

Usage

The portfinder module has a simple interface:

const portfinder = require('portfinder');

portfinder.getPort(function (err, port) {
  //
  // `port` is guaranteed to be a free port
  // in this scope.
  //
});

Or using promises:

const portfinder = require('portfinder');

portfinder.getPortPromise()
  .then((port) => {
    //
    // `port` is guaranteed to be a free port
    // in this scope.
    //
  })
  .catch((err) => {
    //
    // Could not get a free port, `err` contains the reason.
    //
  });

Ports search scope

By default portfinder will start searching from 8000 and scan until maximum port number (65535) is reached.

You can change this globally by setting:

portfinder.setBasePort(3000);    // default: 8000
portfinder.setHighestPort(3333); // default: 65535

or by passing optional options object on each invocation:

portfinder.getPort({
  port: 3000,    // minimum port
  stopPort: 3333 // maximum port
}, callback);

Run Tests

npm test

Author: Charlie Robbins

Author/Maintainer: Erik Trom

License: MIT/X11