url-join

url-join is a tiny, dependency-free utility that joins any number of URL fragments — base URLs, path segments, query strings — into a single, correctly-formatted URL. It handles the fiddly edge cases of manual string concatenation: collapsing duplicate slashes, preserving the protocol’s double-slash, merging multiple query-string fragments with the right separators, and correctly handling file:// and IPv6 host URLs.

The entire implementation is a single ESM function (urlJoin(...args) or urlJoin([args])) with no runtime dependencies, making it a drop-in replacement for the common but error-prone pattern of concatenating strings with template literals or manual slash-trimming.

What You Get

• A single urlJoin(...parts) function accepting either variadic string arguments or a single array
• Automatic normalization of duplicate slashes between joined segments
• Correct handling of protocol double-slashes, file:// triple-slash paths, and IPv6 host brackets
• Merging of multiple query-string fragments across joined segments into one ?/&-correct query string
• Zero runtime dependencies and a TypeScript declaration file shipped with the package

Common Use Cases

• Building a full request URL from a configurable base URL plus a resource path in an API client
• Combining a CDN or asset base path with per-file paths without manual slash bookkeeping
• Joining route segments in server-side routing code where paths are assembled dynamically
• Merging query parameters contributed by different parts of a codebase into one valid query string

Under The Hood

Architecture The library is a single exported function (lib/url-join.js) built around one internal normalize(strArray) helper: it filters empty segments, special-cases a leading bare protocol or leading slash by folding it into the next segment, applies protocol-specific slash rules (file:/// gets three slashes, everything else two), then iterates the remaining segments trimming leading/trailing slashes before rejoining them with single slashes and finally collapsing/re-merging query-string separators (?/&) and any hash fragment.

Tech Stack Pure, dependency-free JavaScript (ESM only, type: module) with no runtime dependencies at all; the sole devDependency is conventional-changelog for release notes. Node’s built-in node --test runner is used directly instead of a third-party test framework, keeping the entire toolchain minimal.

Code Quality The test/tests.js file (323 lines) exercises a large matrix of edge cases — protocol handling, IPv6 hosts, file:// URLs, query-string merging, hash fragments, and empty/whitespace segments — giving strong confidence in correctness for a function whose entire value proposition is handling string-joining edge cases correctly. The implementation itself is a single file with clear inline comments explaining each normalization step, though it favors dense regex-based string manipulation over more explicit parsing, which raises the bar slightly for a newcomer to modify safely.

API Design The API is about as small as possible: one function, accepting either spread arguments or a single array, with no configuration object or options to learn. This makes adoption instantaneous for the common case, though the tradeoff is that any non-default joining behavior (e.g. custom slash handling) isn’t configurable and would require a different tool or a fork.