# whatwg-url-minimum

> Derivative of whatwg-url without unicode handling and optimized for Expo

Latest version **0.2.0** (published 2026-07-15) · MIT license · 0 weekly downloads

## Install

```sh
npm install whatwg-url-minimum
pnpm add whatwg-url-minimum
yarn add whatwg-url-minimum
bun add whatwg-url-minimum
```

## Health

**Score 75/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score.

Warnings: low downloads; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.2.0 |
| Published | 2026-07-15 |
| First published | 2026-01-29 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 210 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 1 |
| Author | Phil Pluckthun |
| Maintainers | philpl |

## Links

- npm: https://www.npmjs.com/package/whatwg-url-minimum
- Repository: https://github.com/expo/whatwg-url-minimum
- Homepage: https://github.com/expo/whatwg-url-minimum#readme
- Issues: https://github.com/expo/whatwg-url-minimum/issues
- npm.io page: https://npm.io/package/whatwg-url-minimum

## Recent versions

- 0.2.0 (latest) — 2026-07-15
- 0.2.0-canary-cadc8fcce232c7d8b7dae8df86f2bb4c6883ccbf (canary) — 2026-07-15
- 0.2.0-canary-d960ea929d423affd716f581a9fc08b3ff182997 — 2026-07-15
- 0.1.3-canary-ab94201f67ae01773fcbd3a1d492b84ce6dcbd12 — 2026-07-15
- 0.1.3-canary-a3a658364cdead6da100c25396bc1c9ce87db24a — 2026-07-15
- 0.1.3-canary-76eff997fe3a60932e19fef50bbfb0b43f4b4e98 — 2026-07-15
- 0.1.3-canary-8ffbfd68b02580cb34ca27aaac4d2ece02f21b14 — 2026-07-15
- 0.1.2 — 2026-05-07
- 0.1.2-canary-c05220356504d588be9954fe9f861212dd21af2a — 2026-05-07
- 0.1.1 — 2026-01-29
- 0.1.1-canary-39eae06e7667482a9c115545d806cc17ae22b590 — 2026-01-29
- 0.1.0 — 2026-01-29
- 0.0.1 — 2026-01-29

## README

# whatwg-url-minimum

`whatwg-url-minimum` is a compact [WHATWG URL Standard](https://url.spec.whatwg.org/) implementation for JavaScript runtimes that need `URL` and `URLSearchParams` without the size and runtime assumptions of larger URL packages.

It is derived from [jsdom/whatwg-url](https://github.com/jsdom/whatwg-url), ported to TypeScript, and optimized for small bundles and React Native / Expo-style environments.

This package is primarily intended for Expo and React Native projects that need a standards-oriented URL implementation with predictable behavior across JavaScript engines, while keeping application bundles small.

## Implementation

The goal of `whatwg-url-minimum` is to keep the observable `URL` and `URLSearchParams` behavior close to the platform standard while reducing implementation size and avoiding runtime features that are not consistently available outside browsers and Node.js.

The implementation focuses on:

- **Compact parser code**: A small TypeScript URL parser with special-scheme, file URL, host, path, query, and fragment handling.
- **Small IDNA/TR46 support**: Domain normalization includes UTS #46 mapping, punycode encoding, joiner validation, and selected validity checks without shipping a full Unicode processing stack.
- **Fast `URLSearchParams` operations**: Query parsing, mutation, sorting, and serialization are optimized for repeated use.

## Quick Start

```ts
import { URL, URLSearchParams } from 'whatwg-url-minimum';

const url = new URL('https://Bücher.de/search?q=hello world');

url.hostname; // "xn--bcher-kva.de"
url.searchParams.append('page', '1');
url.href; // "https://xn--bcher-kva.de/search?q=hello%20world&page=1"

const params = new URLSearchParams('a=1&a=2');
params.getAll('a'); // ["1", "2"]
```

## API Reference

### `class URL`

`URL` follows the standard constructor and static helper shape:

```ts
new URL(input: string, base?: string);
URL.canParse(input: string, base?: string): boolean;
URL.parse(input: string, base?: string): URL | null;
```

Supported instance properties and methods include the standard URL surface:

- `href`
- `origin`
- `protocol`
- `username`
- `password`
- `host`
- `hostname`
- `port`
- `pathname`
- `search`
- `searchParams`
- `hash`
- `toString()`
- `toJSON()`

### `class URLSearchParams`

`URLSearchParams` supports the standard constructor forms and mutation/query methods:

```ts
new URLSearchParams();
new URLSearchParams('a=1&b=2');
new URLSearchParams([['a', '1']]);
new URLSearchParams({ a: '1' });
```

Supported methods and properties include:

- `append(name, value)`
- `delete(name, value?)`
- `get(name)`
- `getAll(name)`
- `has(name, value?)`
- `set(name, value)`
- `sort()`
- `forEach(callback, thisArg?)`
- `keys()`
- `values()`
- `entries()`
- `size`
- `toString()`

## Conformance

The test suite runs downloaded Web Platform Tests for URL parsing, URL setters, `URLSearchParams`, static helpers, and WebIDL behavior. It also includes local coverage for WPT resources that cannot be run directly in Vitest, such as `toascii.window.js` and `percent-encoding.window.js`.

Additional local tests compare IDNA/TR46 behavior against `whatwg-url` for the active `toascii.json` cases and seeded mixed-script domain cases.

Current known divergence:

- Full RFC 5893 CheckBidi validation is not implemented. The implementation contains a small mixed Latin/RTL rejection that covers the active URL WPT `toascii` cases without adding generated Bidi_Class tables.
- Revalidation of pre-existing `xn--` labels after UTS #46 mapping is intentionally omitted. This avoids shipping a punycode decoder solely for obsolete/removed IDNA validity coverage.
- `IdnaTestV2-removed.any.js` is intentionally omitted because it contains obsolete/deprecated IDNA cases outside this package's active conformance target.

---
_Source: https://npm.io/package/whatwg-url-minimum · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._