portfinder

By default, portfinder searches from port 8000 up to 65535. You can modify this behavior in two ways:

1. Global Configuration

Set the search boundaries globally for all subsequent calls using setBasePort and setHighestPort.

2. Per-invocation Configuration

Pass an options object directly to getPort to define a specific range for a single request.

Options object keys:

• port: The minimum port to start searching from.
• stopPort: The maximum port to search up to.

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

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

You can install the portfinder package using npm, yarn, or bun.

npm install portfinder

If you prefer working with Promises, use getPortPromise(). It resolves with the free port or rejects with an error if no free port could be found within the search scope.

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.
    //
  });

The getPort method uses a callback pattern to find an available port. The returned port is guaranteed to be free within the configured search scope.

const portfinder = require('portfinder');

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

When calling getSocket or getSocketPromise, you can pass a SocketFinderOptions object:

const options: SocketFinderOptions = {
  path: '/tmp/app.sock',
  mod: 0o777
};

When calling getPort, getPortPromise, or getPorts, you can pass a PortFinderOptions object to refine the search:

const options: PortFinderOptions = {
  host: '127.0.0.1',
  port: 3000,
  stopPort: 4000
};

Use setBasePath(path: string) to set the default directory/path where socket files will be searched or created. This updates the basePath variable.

import { setBasePath } from 'portfinder';

setBasePath('/var/run/my-app');

Use getPort to find an unbound port on the current machine. It supports three usage patterns:

1. Promise-based: Returns a Promise<number> when called with an options object.
2. Callback-only: Returns void and executes a callback with (err, port) => void.
3. Options + Callback: Returns void and executes a callback after applying the provided PortFinderOptions.

Note: If you provide an options object, it returns a Promise. If you provide a callback, it uses the callback pattern.

// Promise usage
const port = await getPort({ port: 3000 });

// Callback usage
getPort({ port: 3000 }, (err, port) => {
  if (err) throw err;
  console.log(port);
});

Use getSocket to find or create an available socket file path. It supports Promise-based usage via getSocketPromise(options) or callback-based usage via getSocket(options, callback).

Returns a string representing the path to the socket.

// Promise usage
const socketPath = await getSocket({ path: '/tmp/my-socket.sock' });

Use getPorts to retrieve an array of unbound ports. It supports:

1. Promise-based: getPorts(count, options) returns Promise<Array<number>>.
2. Callback-based: getPorts(count, callback) or getPorts(count, options, callback).
3. Promise-specific helper: getPortsPromise(count, options) returns Promise<Array<number>>.

// Get 5 available ports starting from port 8000
const ports = await getPorts(5, { port: 8000 });

You can globally define the range of ports that portfinder is allowed to search within using these functions:

• setBasePort(port: number): Sets the lowest port to begin any port search from. This updates the basePort variable.
• setHighestPort(port: number): Sets the highest port to end any port search from. This updates the highestPort variable.

import { setBasePort, setHighestPort } from 'portfinder';

setBasePort(1000);
setHighestPort(5000);