Skip to content

funbox/free-port-finder

master
Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

@funboxteam/free-port-finder

npm

The package checks availability of the passed port, or tries to find the first available port starting from the passed one.

По-русски

Rationale

When you start a TCP (or HTTP) server on localhost you want to be sure that the desirable port isn't occupied or you don't really care and want to get the first available one.

This tiny tool takes on this task.

Installation

npm install --save-dev @funboxteam/free-port-finder

Usage

findFreePort(port: number, host?: string): Promise<number> searches for the available port starting from the passed one:

const { findFreePort } = require('@funboxteam/free-port-finder');

const port = 3000;

findFreePort(port)
  .then(freePort => {
    config.devServer.port = freePort;
  });

isPortFree(port: number, host?: string): Promise<bool> checks the availability of the passed port:

const { isPortFree } = require('@funboxteam/free-port-finder');

const port = 3000;

isPortFree(port)
  .then(isFree => {
    if (isFree) {
      // start
    } else {
      // cancel
    }
  });

It is possible to pass host value as second parameter. The default host value is '0.0.0.0'.

To check if port on specified host is available:

const { isPortFree } = require('@funboxteam/free-port-finder');

const port = 3000;
const host = '127.0.0.1';

isPortFree(port, host)
  .then(isFree => {
    if (isFree) {
      // start
    } else {
      // cancel
    }
  });

How it works

In order to understand whether the port is free or not, this package tries to run a TCP-server on the specified port. If the server starts, then package kills it and signals that the port is free. If an EADDRINUSE error occurs, it signals that the port is busy. If any other error occurs, then package throws it out.

This solution has both pros and cons.

Cons:
In some OS incorrect SO_REUSEADDR processing is possible, and a free port can be signaled as busy (but not vice versa).

Pros:
It would be possible to go the other way, and try to connect to sockets at a specified address, rather than run server on them. But in this case, it is possible that the connection to a socket may initiate some process in its handler, which could potentially be irreversible. Therefore, current solution is safe.

Sponsored by FunBox

About

Tiny utility for checking ports availability

Topics

Resources

License

Stars

Watchers

Forks