{"id":18969512,"url":"https://github.com/brionmario/dev-server-ports","last_synced_at":"2026-07-08T19:31:51.144Z","repository":{"id":41888825,"uuid":"474418279","full_name":"brionmario/dev-server-ports","owner":"brionmario","description":"😎 Handle dev server ports like a boss","archived":false,"fork":false,"pushed_at":"2023-08-20T17:36:34.000Z","size":1038,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-10-25T22:07:41.460Z","etag":null,"topics":["featured-project","portfolio"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/brionmario.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":"2022-03-26T17:26:26.000Z","updated_at":"2022-11-20T17:26:36.000Z","dependencies_parsed_at":"2024-11-08T14:53:25.742Z","dependency_job_id":"fef78e51-cd31-40ff-9718-252ba426cf2c","html_url":"https://github.com/brionmario/dev-server-ports","commit_stats":{"total_commits":76,"total_committers":2,"mean_commits":38.0,"dds":"0.013157894736842146","last_synced_commit":"9dd67bb203720fc7d48552903b3bb9a95e3c43d1"},"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/brionmario/dev-server-ports","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brionmario%2Fdev-server-ports","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brionmario%2Fdev-server-ports/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brionmario%2Fdev-server-ports/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brionmario%2Fdev-server-ports/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/brionmario","download_url":"https://codeload.github.com/brionmario/dev-server-ports/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brionmario%2Fdev-server-ports/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35276649,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-08T02:00:06.796Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["featured-project","portfolio"],"created_at":"2024-11-08T14:53:19.192Z","updated_at":"2026-07-08T19:31:51.126Z","avatar_url":"https://github.com/brionmario.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\" style=\"padding-top: 20px\"\u003e\n  \u003cimg src=\"./docs/resources/logo.png\" height=\"96\"\u003e\n  \u003cp align=\"center\"\u003eHandle dev server ports like a boss 😎\u003c/p\u003e\n\u003c/p\u003e\n\n\u003cdiv align=\"center\"\u003e\n\n  \u003ca href=\"\"\u003e[![npm version](https://badge.fury.io/js/dev-server-ports.svg)](https://badge.fury.io/js/dev-server-ports)\u003c/a\u003e\n  \u003ca href=\"\"\u003e[![Build](https://github.com/brionmario/dev-server-ports/actions/workflows/build.yml/badge.svg)](https://github.com/brionmario/dev-server-ports/actions/workflows/build.yml)\u003c/a\u003e\n  \u003ca href=\"\"\u003e[![Release](https://github.com/brionmario/dev-server-ports/actions/workflows/release.yml/badge.svg)](https://github.com/brionmario/dev-server-ports/actions/workflows/release.yml)\u003c/a\u003e\n  \u003ca href=\"\"\u003e\u003c!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section --\u003e[![All Contributors](https://img.shields.io/badge/all_contributors-1-orange.svg?style=flat-square)](#contributors-)\u003c!-- ALL-CONTRIBUTORS-BADGE:END --\u003e\u003c/a\u003e\n  \u003ca href=\"\"\u003e[![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-yellow.svg)](http://commitizen.github.io/cz-cli/)\u003c/a\u003e\n  \u003ca href=\"\"\u003e[![semantic-release: angular](https://img.shields.io/badge/semantic--release-angular-e10079?logo=semantic-release)](https://github.com/semantic-release/semantic-release)\u003c/a\u003e\n\u003c/div\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./docs/resources/banner.png\"\u003e\n\u003c/p\u003e\n\n# Table of Contents\n\n- 💡 [Inspiration](#inspiration)\n- [Prerequisites](#prerequisites)\n- [API Reference](#api-reference)\n    - [findPort](#findPort)\n- [Examples](#examples)\n- [Contributors](#contributors)\n- [License](#license)\n\n# Inspiration\n\nSometimes we need to show our users a bit more context when the development ports conflict. Most of the already available packages lacks the support to customize the prompts. This package tries to solve this issue along with a lot more helpers that would supplement development pipelines when working with dev ports.\n\n# Prerequisites\n\n- [Node.js](https://nodejs.org/en/download/) version `\u003e=12.0.0` is required. ([Inquirer.js](https://github.com/SBoudrias/Inquirer.js) version used in the isn't compatible with lower node versions.)\n\n# API Reference\n\n## `findPort`\n\n```js\nfindPort(\n  port: number,\n  hostname?: string,\n  shouldFallback?: boolean | undefined,\n  reporter?: {\n    extensions: Partial\u003cIReporterExtensions\u003e;\n    overrides: Partial\u003cIReporter\u003e;\n  }\n)\n```\n\n### Returns\n\nA `Promise` of type `number`.\n\n### Description\n\n|Argument|Type|Default Value|Required|Description|\n|--------|----|-------------|--------|-----------|\n|port|number| - |Yes|Prefered port to fire up the app in.|\n|hostname|string| - |No|Host name of the application. `Ex: localhost or 127.0.0`|\n|shouldFallback|boolean| true |No|Should the function return a an available port. You can set this to false if you wish to show just a message to the user in case of a port conflict.|\n|reporter|`{ extensions: Partial\u003cIReporterExtensions\u003e; overrides: Partial\u003cIReporter\u003e;}`| - |No|Customize the messages shown to the user incase of a port conflict.|\n\n### Usage\n\n#### Basic Usage\n\n`PORT` resolves to 3000 if the port is available. If the port is unavailable, users will get the chance to fallback to the nearest available port.\n\n```js\nconst { findPort } = require(\"dev-server-ports\");\n\nconst PORT = await findPort(3000);\n```\n\n##### Output\n\n![Image](./docs/resources/port-conflict-output.png)\n\n#### Resolve port with no fallback\n\nIf the port is not available, only a prompt will be shown to the user. You can customize this prompt to match the requirements.\n\n```js\nconst { findPort } = require(\"dev-server-ports\");\n\nconst PORT = await findPort(3000, \"localhost\", false, {\n  extensions: {\n    BEFORE_getProcessTerminationMessage: () =\u003e {\n      return `Read through the README.md (https://github.com/brionmario/dev-server-ports/blob/main/README.md)\nfile for more information.`;\n    }\n  }\n});\n```\n\n##### Output\n\n![Image](./docs/resources/port-conflict-no-fallback-output.png)\n\n# Examples\n\n## Webpack Dev Server v4 example\n\nUsage of the library with [Webpack Dev Server v4](https://github.com/webpack/webpack-dev-server/releases/tag/v4.8.1) which is the latest version at the time of writting, can be found below.\n\n\u003e 💡 Version 4.x doesn't allow to pass a function that returns a promise straight in to the `port` field of the `devServer` configuration.\n\n- [Source Code](./examples/webpack-dev-server-4.x/).\n# Contributors ✨\n\nThanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section --\u003e\n\u003c!-- prettier-ignore-start --\u003e\n\u003c!-- markdownlint-disable --\u003e\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\"\u003e\u003ca href=\"http://www.brionmario.com/\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/25959096?v=4?s=100\" width=\"100px;\" alt=\"\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eBrion Mario\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/Brion Mario/dev-server-ports/commits?author=brionmario\" title=\"Code\"\u003e💻\u003c/a\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n\u003c!-- markdownlint-restore --\u003e\n\u003c!-- prettier-ignore-end --\u003e\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:END --\u003e\n\nThis project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!\n\n# License\n\nThis project is licensed under the MIT License. See the [LICENSE](./LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrionmario%2Fdev-server-ports","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbrionmario%2Fdev-server-ports","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrionmario%2Fdev-server-ports/lists"}