Skip to content
Please note that GitHub no longer supports Internet Explorer.

We recommend upgrading to the latest Microsoft Edge, Google Chrome, or Firefox.

Learn more
A 1.5kB browser polyfill for the Node.js `URL` and `URLSearchParams` classes.
JavaScript
Branch: master
Clone or download
Cannot retrieve the latest commit at this time.
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github/workflows fix(action): remove `nyc` runner Dec 12, 2019
src fix: proxy custom protocols for parsing Dec 17, 2019
test
.editorconfig initial commit Dec 12, 2019
.gitignore chore: install & configure jest w/ puppeteer Dec 12, 2019
license initial commit Dec 12, 2019
package.json 1.0.1 Dec 17, 2019
readme.md chore: add custom protocol w/ hostname example Dec 17, 2019
urlshim.d.ts fix(types): exports Dec 17, 2019

readme.md

url-shim codecov

A 1.53kB browser polyfill for the Node.js URL and URLSearchParams classes.

Why?

  • All browser implementations are not 100% identical to the Node.js implementation.
    For example, browsers have issue with custom protocols, which affects the origin and pathname parsing.

  • Most polyfills match the browser implementations.
    But what if you have a "universal app" and want to guarantee client/server uniformity?

  • Most polyfills immediately (albeit, conditionally) mutate global scope.
    You can't declaratively import their implementations for standalone usage.

Note: The only other library that satisfies these requirements is whatwg-url, but it weighs 87.6 kB (gzip)!

This module is available in three formats:

  • ES Module: dist/urlshim.mjs
  • CommonJS: dist/urlshim.js
  • UMD: dist/urlshim.min.js

Install

$ npm install --save url-shim

Usage

import { URL, URLSearchParams } from 'url-shim';

// composition
new URL('/foo', 'https://example.org/').href;
//=> "https://example.org/foo"

// unicode -> ASCII conversion
new URL('https://測試').href;
//=> "https://xn--g6w251d/"

// custom protocols w/ path
new URL('webpack:///src/bundle.js');
//=> { protocol: "webpack:", pathname: "/src/bundle.js", ... }

// custom protocols w/ hostname
new URL('git://github.com/lukeed/url-shim');
//=> { protocol: "git:", hostname: "github.com", pathname: "/lukeed/url-shim", ... }

new URL('http://foobar.com/123?a=1&b=2').searchParams instanceof URLSearchParams;
//=> true

const params = new URLSearchParams('foo=bar&xyz=baz');
for (const [name, value] of params) {
  console.log(name, value);
}
// Prints:
//   foo bar
//   xyz baz

API

URL(input, base?)

Size (gzip): 1.53 kB

See Node.js documentation for info.

Important: Requires a browser environment because document.createElement is used for URL parsing.

URLSearchParams(input?)

Size (gzip): 944 B

See Node.js documentation for info.

License

MIT © Luke Edwards

You can’t perform that action at this time.