get-port-please

What is get-port-please?

The `get-port-please` npm package is designed to help developers find an available port on the host machine. It is particularly useful in scenarios where an application needs to start a server but must avoid port conflicts with other applications. This package offers flexibility in selecting ports, including the ability to specify preferred port ranges or fallback to any available port if the preferred ones are occupied.

What are get-port-please's main functionalities?

Getting an available port

This feature allows you to get an available port on the machine. If no arguments are passed, it returns any available port.

const getPort = require('get-port-please');

getPort().then(port => {
  console.log(`Available port: ${port}`);
});

Specifying preferred ports

This feature enables specifying an array of preferred ports. The function will return the first available port from the specified list or any available port if none from the list are free.

const getPort = require('get-port-please');

getPort({ preferredPorts: [3000, 3001, 3002] }).then(port => {
  console.log(`Available port: ${port}`);
});

Specifying port ranges

This feature allows specifying ranges of ports to check for availability. It's useful when you need a port within a specific range.

const getPort = require('get-port-please');

getPort({ portRanges: [{ from: 8000, to: 8005 }] }).then(port => {
  console.log(`Available port within range: ${port}`);
});

Other packages similar to get-port-please

portfinder

Similar to `get-port-please`, `portfinder` provides a way to get an available port on the host machine. However, `portfinder` focuses more on finding an open port by incrementing from a base port, rather than specifying preferred ports or ranges.

get-port

The `get-port` package also helps in finding an available port. While it shares similar basic functionality with `get-port-please`, it does not offer the same level of control over specifying port ranges or preferred port lists.

README

🔌 get-port-please

Get an available TCP port to listen

Usage

Install package:

npm i get-port-please

// ESM
import {
  getPort,
  checkPort,
  getRandomPort,
  waitForPort,
} from "get-port-please";

// CommonJS
const {
  getPort,
  checkPort,
  getRandomPort,
  waitForPort,
} = require("get-port-please");

getPort(options?: GetPortOptions): Promise<number>
checkPort(port: number, host?: string): Promise<number | false>
waitForPort(port: number, options): Promise<number | false>

Try sequence is: port > ports > random

Options

interface GetPortOptions {
  name?: string;

  random?: boolean;
  port?: number;
  portRange?: [fromInclusive: number, toInclusive: number];
  ports?: number[];
  host?: string;

  memoDir?: string;
  memoName?: string;
}

name

Unique name for port memorizing. Default is default.

random

If enabled, port and ports will be ignored. Default is false.

port

First port to check. Default is process.env.PORT || 3000

ports

Extended ports to check.

portRange

Extended port range to check.

The range's start and end are inclusive, i.e. it is [start, end] in the mathematical notion. Reversed port ranges are not supported. If start > end, then an empty range will be returned.

alternativePortRange

Alternative port range to check as fallback when none of the ports are available.

The range's start and end are inclusive, i.e. it is [start, end] in the mathematical notion. Reversed port ranges are not supported. If start > end, then an empty range will be returned.

The default range is [3000, 3100] (only when port is unspecified).

host

The host to check. Default is process.env.HOST otherwise all available hosts will be checked.

License

MIT

Changelog

v3.1.2

compare changes

🩹 Fixes

• Accept ipv6 as valid hostname (d537a51)
• Use closed ranges as port ranges (#66)
• Ranges now work even if port is unset in options (#72)
• Don't use random port by default if user specified any port (#65)

💅 Refactors

• Correct typos in GetPortError message (#77)
• Fix typo in error message (#73)
• Improve log when using alternative port (#78)

🏡 Chore

• Update fallback message (1f45050)
• Update dependencies and lockfile (62735f6)

✅ Tests

• Simplify (9dccfd9)
• Update snapshot (59cdd8c)

❤️ Contributors

• Pooya Parsa (@pi0)
• Filip Joelsson [e-mail]
• Daniel Roe [e-mail]
• Vladimir Vagaytsev (@vvagaytsev)
• Yu Le [e-mail]