Registry / http-networking / universal-url

universal-url

library2.0.0jsnpmunverified

The `universal-url` package provides a robust and consistent implementation of the WHATWG `URL` and `URLSearchParams` APIs, ensuring their availability across diverse JavaScript environments, including Node.js (versions 6 and above) and web browsers. This library intelligently determines whether to leverage the native `URL` implementation (available in Node.js versions `>= 8`) or to transparently apply a polyfill using the `whatwg-url` package for environments lacking native support, such as older Node.js versions (`< 8`) and some web browsers. The current stable version is 2.0.0. While a specific release cadence isn't detailed, updates typically align with bug fixes or evolutions in the underlying WHATWG URL specification. Its key differentiator is providing a singular, abstracted API layer that allows developers to write URL parsing and manipulation code once, confident that it will behave identically regardless of the execution environment, eliminating the need for conditional imports or polyfill management.

http-networking serialization

npm install universal-url

github ↗package ↗

INSTALL

IMPORT

SIG · UNIVERSAL-URL

universal-url

http-networkingjavascriptv2.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

URL, URLSearchParams

✓ const {URL, URLSearchParams} = require('universal-url');

✗ import { URL, URLSearchParams } from 'universal-url';

For Node.js environments `>=6` as specified by `engines`, CommonJS `require` is the canonical way to import these classes. Direct ESM `import` statements might not work without additional tooling or if targeting older Node.js runtimes that lack native ESM support for CommonJS modules.

Global shim function

✓ require('universal-url').shim();

✗ import { shim } from 'universal-url'; shim();

The `shim()` method is called directly on the module object obtained via `require()` to apply the `URL` and `URLSearchParams` polyfills globally, making them available on the global scope without explicit imports.

Demonstrates importing `URL` and `URLSearchParams` using CommonJS `require` and basic URL parsing, manipulation, and search parameter handling.

const {URL, URLSearchParams} = require('universal-url'); // Create a new URL object const url = new URL('http://example.com/path?param1=value1&param2=value2'); console.log(`Hostname: ${url.hostname}`); // Hostname: example.com console.log(`Pathname: ${url.pathname}`); // Pathname: /path // Access URL search parameters console.log(`Param1 value: ${url.searchParams.get('param1')}`); // Param1 value: value1 // Modify URL search parameters url.searchParams.set('param3', 'newValue'); url.searchParams.delete('param2'); console.log(`Modified URL: ${url.toString()}`); // Modified URL: http://example.com/path?param1=value1&param3=newValue // Use the global shim for environments without native URL // require('universal-url').shim(); // const globalUrl = new URL('https://domain.org/');

Debug

Known issues

gotchaThe package uses native WHATWG URL implementation for Node.js versions `>= 8` but falls back to a polyfill (via `whatwg-url`) for Node.js `< 8` and browsers without native support. While API is consistent, underlying performance characteristics might differ slightly.

fix

No direct fix needed as this is handled automatically. Be aware of potential subtle differences if profiling performance across environments.

affects: <8.0.0

gotchaFor web browser builds, `universal-url` includes the potentially large `whatwg-url` shim. This can significantly increase bundle size if your target browsers generally have native `URL` support.

fix

Consider using `universal-url-lite` as an alias in your build configuration (e.g., Webpack, Rollup) for browser targets to reduce bundle size if native URL support is expected.

affects: >=1.0.0

Errors

Common errors & fixes

ReferenceError: URL is not defined

`URL` or `URLSearchParams` classes are not imported or the global shim has not been applied.

fix

Ensure you either import `const {URL} = require('universal-url');` or apply the global shim via `require('universal-url').shim();` at the start of your application.

TypeError: Invalid URL

The string provided to the `URL` constructor does not represent a valid URL according to WHATWG specification.

fix

Verify that the input string is a well-formed absolute or relative URL. For relative URLs, ensure a valid `base` URL is also provided (e.g., `new URL('/path', 'http://example.com/')`).

webpack or rollup build warnings/errors related to large bundle size for browser

The `universal-url` package includes the full `whatwg-url` polyfill, which can be substantial for browser bundles where native `URL` support is common.

fix

If targeting modern browsers, alias `universal-url` to `universal-url-lite` in your build configuration to avoid including the unnecessary polyfill. For example, in Webpack: `resolve: { alias: { 'universal-url': 'universal-url-lite' } }`.

Upgrade

Version history

2.0.0latest on npm

Audit

Dependencies

whatwg-urlrequiredUsed as a shim for environments without native WHATWG URL support (Node.js < 8, some browsers).

Agent activity

10 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/stevenvachon/universal-url ↗

packagehttps://www.npmjs.com/package/universal-url ↗