{"id":21301718,"url":"https://github.com/funbox/free-port-finder","last_synced_at":"2025-07-11T20:31:17.910Z","repository":{"id":42721217,"uuid":"279618656","full_name":"funbox/free-port-finder","owner":"funbox","description":"Tiny utility for checking ports availability","archived":false,"fork":false,"pushed_at":"2023-07-18T22:53:44.000Z","size":544,"stargazers_count":7,"open_issues_count":1,"forks_count":0,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-06-28T20:18:19.304Z","etag":null,"topics":["http","port-check","server","tcp"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/funbox.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-07-14T15:09:03.000Z","updated_at":"2024-08-13T20:23:46.000Z","dependencies_parsed_at":"2024-06-20T22:00:10.333Z","dependency_job_id":"1d94eba8-ab3a-45ce-8044-8d1bb5dac765","html_url":"https://github.com/funbox/free-port-finder","commit_stats":{"total_commits":58,"total_committers":9,"mean_commits":6.444444444444445,"dds":0.6206896551724138,"last_synced_commit":"832f27e7440fd46b75ac04e9a56b3b6048c129a4"},"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/funbox/free-port-finder","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/funbox%2Ffree-port-finder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/funbox%2Ffree-port-finder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/funbox%2Ffree-port-finder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/funbox%2Ffree-port-finder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/funbox","download_url":"https://codeload.github.com/funbox/free-port-finder/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/funbox%2Ffree-port-finder/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264892160,"owners_count":23679243,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["http","port-check","server","tcp"],"created_at":"2024-11-21T15:50:31.512Z","updated_at":"2025-07-11T20:31:12.899Z","avatar_url":"https://github.com/funbox.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @funboxteam/free-port-finder\n\n[![npm](https://img.shields.io/npm/v/@funboxteam/free-port-finder.svg)](https://www.npmjs.com/package/@funboxteam/free-port-finder)\n\nThe package checks availability of the passed port, or tries to find the first available port starting from the passed one.\n\n[По-русски](./README.ru.md)\n\n## Rationale\n\nWhen you start a TCP (or HTTP) server on localhost you want to be sure that the desirable port isn't occupied \nor you don't really care and want to get the first available one. \n\nThis tiny tool takes on this task. \n\n## Installation\n\n```bash\nnpm install --save-dev @funboxteam/free-port-finder\n```\n\n## Usage\n\n`findFreePort(port: number, host?: string): Promise\u003cnumber\u003e` searches for the available port starting from the passed one:\n\n```js\nconst { findFreePort } = require('@funboxteam/free-port-finder');\n\nconst port = 3000;\n\nfindFreePort(port)\n  .then(freePort =\u003e {\n    config.devServer.port = freePort;\n  });\n```\n\n`isPortFree(port: number, host?: string): Promise\u003cbool\u003e` checks the availability of the passed port:\n\n```js\nconst { isPortFree } = require('@funboxteam/free-port-finder');\n\nconst port = 3000;\n\nisPortFree(port)\n  .then(isFree =\u003e {\n    if (isFree) {\n      // start\n    } else {\n      // cancel\n    }\n  });\n```\n\nIt is possible to pass host value as second parameter. The default host value is `'0.0.0.0'`.\n\nTo check if port on specified host is available:\n\n```js\nconst { isPortFree } = require('@funboxteam/free-port-finder');\n\nconst port = 3000;\nconst host = '127.0.0.1';\n\nisPortFree(port, host)\n  .then(isFree =\u003e {\n    if (isFree) {\n      // start\n    } else {\n      // cancel\n    }\n  });\n```\n\n## How it works\n\nIn order to understand whether the port is free or not, this package tries to\nrun a TCP-server on the specified port. If the server starts, then package kills\nit and signals that the port is free. If an `EADDRINUSE` error occurs, it signals\nthat the port is busy. If any other error occurs, then package throws it out.\n\nThis solution has both pros and cons.\n\n**Cons:**\u003cbr/\u003e\nIn some OS incorrect `SO_REUSEADDR` processing is possible, and a free port can\nbe signaled as busy (but not vice versa).\n\n**Pros:**\u003cbr/\u003e\nIt would be possible to go the other way, and try to connect to sockets at\na specified address, rather than run server on them. But in this case,\nit is possible that the connection to a socket may initiate some process\nin its handler, which could potentially be irreversible. Therefore,\ncurrent solution is safe.\n\n[![Sponsored by FunBox](https://funbox.ru/badges/sponsored_by_funbox_centered.svg)](https://funbox.ru)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffunbox%2Ffree-port-finder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffunbox%2Ffree-port-finder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffunbox%2Ffree-port-finder/lists"}