URL API Polyfill

1.1.0 verified Fri May 01 auth: no javascript

A lightweight polyfill for the URL and URLSearchParams APIs in environments where they are not natively supported, such as older browsers (IE, legacy Edge) or Node.js versions before v10. Current stable version is 1.1.0. No breaking changes since first release. Simpler than `whatwg-url` — focused solely on browser compatibility without extra parsing logic.

Common errors

error import { URL } from 'url-api-polyfill' → 'URL' is not exported from 'url-api-polyfill' ↓

cause Wrong import style: the package only has side effects, no named exports.

fix

Change to import 'url-api-polyfill'.

error TypeError: URL is not a constructor ↓

cause The polyfill was not imported before using URL, or it's not installed.

fix

Ensure the package is installed and imported via import 'url-api-polyfill' at the entry point.

Warnings

gotcha Importing the module does not return any exports — it only patches globals. Do not try to destructure imports. ↓

fix Use `import 'url-api-polyfill'` (no named imports). After import, URL and URLSearchParams are globally available.

gotcha The polyfill may not perfectly replicate native URL behavior in all edge cases (e.g., IDN support, percent-encoding quirks). ↓

fix Test your specific use cases. Consider using `whatwg-url` or native APIs in modern environments.

deprecated This package is rarely updated; native support is now widespread. Consider dropping the polyfill if you target modern browsers or Node >=10. ↓

fix Remove the polyfill and use native URL/URLSearchParams. Polyfill conditionally or use a more up-to-date library like `whatwg-url`.

Install

npm install url-api-polyfill

yarn add url-api-polyfill

pnpm add url-api-polyfill

Imports

URL

wrong

import { URL } from 'url-api-polyfill'

correct

import 'url-api-polyfill';
// URL is then globally available

This polyfill mutates the global scope. No named import needed.

URLSearchParams

wrong

const { URLSearchParams } = require('url-api-polyfill')

correct

import 'url-api-polyfill';
// URLSearchParams is globally available

Import the module for the side effect; both classes become global.

require (CJS)

wrong

const url = require('url-api-polyfill');
// url is an empty object

correct

require('url-api-polyfill');
// After require, URL and URLSearchParams are global

CJS import does not export anything; it only patches globals.

Quickstart

Demonstrates side-effect import and usage of global URL and URLSearchParams.

// Install: npm install url-api-polyfill
import 'url-api-polyfill';

const url = new URL('https://user:pass@example.com:8080/path?query=1#hash');
console.log(url.protocol);   // 'https:'
console.log(url.hostname);   // 'example.com'
console.log(url.port);       // '8080'
console.log(url.pathname);   // '/path'
console.log(url.search);     // '?query=1'
console.log(url.hash);       // '#hash'
console.log(url.username);   // 'user'
console.log(url.password);   // 'pass'

const params = new URLSearchParams('key1=value1&key2=value2');
console.log(params.get('key1')); // 'value1'