urlpattern-polyfill

urlpattern-polyfill implements the WICG URLPattern specification, a pattern-matching API purpose-built for matching URLs by protocol, hostname, pathname, search, and hash using a path-to-regexp-inspired syntax. It ships a Parser class translated directly from Chromium’s own C++ implementation, so it behaves identically to the native browser API rather than approximating it, and it validates that behavior by running the same Web Platform Tests suite used to certify the real implementation.

The package only installs itself onto globalThis.URLPattern when the feature isn’t already present, so it’s safe to import unconditionally in code that needs to run in both modern and older environments — including Node.js, service workers, and any browser lacking native support. It ships as a dual ESM/CJS package with bundled TypeScript types, with zero runtime dependencies of its own.

What You Get

• A URLPattern class matching the native browser API exactly: same constructor signatures (init object, pattern string, string + baseURL), same test()/exec() methods, same per-component readonly properties
• Automatic self-installation onto globalThis.URLPattern only when the native implementation is missing, so imports are safe unconditionally
• Dual-format distribution: ESM (dist/urlpattern.js) and CommonJS (dist/urlpattern.cjs) builds plus bundled .d.ts type definitions
• A parser ported directly from Chromium’s own C++ url_pattern_parser implementation, giving spec-accurate component splitting rather than an approximation
• Support for the experimental “short form” string constructor (e.g. new URLPattern("https://*.example.com/foo/*")) ahead of its landing in Chromium itself

Common Use Cases

• Matching request URLs in a service worker (the original motivating use case for the URLPattern spec)
• Implementing router logic in frameworks or applications that need pattern-based URL matching without pulling in a full routing library
• Filtering or dispatching on same-origin asset requests by extension or path shape (e.g. matching *.jpg or *.png)
• Running URLPattern-based code in Node.js or in older browsers before native support was widespread

Under The Hood

Architecture The entry points (index.js / index.cjs) are thin wrappers that conditionally assign a bundled build onto globalThis.URLPattern. The bundle itself is built via esbuild from src/url-pattern.ts, which defines the URLPattern class and orchestrates a fixed COMPONENTS list (protocol, username, password, hostname, port, pathname, search, hash) through helper functions like extractValues, applyInit, and processBaseURLString. Actual pattern parsing is delegated to url-pattern-parser.ts, a state-machine Parser class ported line-for-line from Chromium’s C++ url_pattern_parser implementation, which walks a token stream produced by the lexer in path-to-regex-modified.ts (a modified fork of path-to-regexp) through explicit states (INIT, PROTOCOL, AUTHORITY, … DONE). url-utils.ts supplies per-component canonicalization and percent-encoding callbacks. The result is a flat, single-purpose pipeline — raw pattern input flows through the parser into per-component pattern strings, then into compiled regular expressions — with no dependency injection or layering beyond parser → pattern → utils, though those three modules are tightly coupled around shared component-string conventions.

Tech Stack Written entirely in TypeScript, targeting ES2022, and bundled with esbuild into both ESM and CJS outputs via wireit-orchestrated build tasks; type declarations are copied alongside the bundles. The package declares zero runtime dependencies, keeping its footprint minimal for both browser and Node.js consumption. Development tooling includes ava for testing, rimraf for cleanup, and a GitHub Actions workflow that runs the test suite on every push.

Code Quality The test suite runs through ava against fixture data pulled directly from the W3C Web Platform Tests project (kept in sync via a dedicated sync-wpt task that fetches from wpt.live), giving genuine cross-implementation conformance coverage rather than hand-written unit tests alone. Additional smoke tests confirm the package loads correctly as ESM, CJS, and TypeScript. Source code is fully typed with explicit interfaces and uses private class fields for encapsulation in the parser. Invalid input throws typed errors matching spec behavior. No dedicated linter or formatter configuration was found in the repository.

API Design The public API is a deliberate one-to-one match for the native browser URLPattern global, so there is effectively no new API surface to learn: the same constructor overloads, the same test()/exec() methods, and the same readonly component properties as the platform standard. Getting started requires a single conditional import line and no configuration. It also exposes an experimental “short form” string constructor ahead of native browser support, giving early access to a convenience the spec was still finalizing.