Portfinder

Portfinder is a small Node.js utility that scans a configurable port range and returns the first free TCP port (or domain socket) it finds, guaranteed available at the moment it’s returned. It solves the common problem of hardcoding a port number in dev servers, test suites, or local tooling, where a hardcoded port can already be in use by another process.

The library exposes both callback (getPort(callback)) and promise-based (getPortPromise()) APIs, with global (setBasePort/setHighestPort) or per-call options to control the scanned range (default: 8000 to 65535). It has no heavyweight dependencies beyond async and debug, making it a lightweight addition to build tools and test harnesses.

What You Get

• Callback-based getPort(callback) API for finding a single free port
• Promise-based getPortPromise() API for use with async/await
• Global range configuration via setBasePort/setHighestPort, or per-call port/stopPort options
• Support for finding a free domain socket in addition to TCP ports
• Zero native dependencies — pure JavaScript with async and debug as its only runtime deps

Common Use Cases

• Dev servers and build tools (webpack-dev-server, browser-sync style tooling) picking an available port instead of hardcoding one
• Test suites and CI pipelines that need a guaranteed-free port per test run to avoid port collisions
• CLI tools that spin up a local server and need to avoid conflicting with a port already in use
• Multi-instance local development setups where several services need distinct, non-conflicting ports

Under The Hood

Architecture - The entire implementation lives in a single file, lib/portfinder.js, which sequentially attempts to bind a Node net.Server (or Unix socket path) to increasing port numbers, closing each successful bind immediately and returning that port to the caller; the async dependency drives the sequential try-next-port control flow. Tech Stack - Pure JavaScript (100% of the codebase) with only async (control-flow helper) and debug (logging) as runtime dependencies, tested with Jest, and shipping hand-written .d.ts type declarations rather than being authored in TypeScript. Code Quality - The test/ directory covers the callback API, promise API, base/highest port configuration, and socket-path lookup; the codebase is small and stable enough that it has seen minimal recent commits, reflected in the low development-activity health score despite being a mature, widely-depended-upon package. API Design - The library exposes exactly two entry points (getPort/getPortPromise) plus two setters (setBasePort/setHighestPort), giving a near-zero learning curve; the callback-first design (with a promise variant added later) reflects its 2012 origins but both styles remain fully supported.