URLPattern comes to Node.js

Cloudflare has contributed a URLPattern implementation to Node.js, available starting with v23.8.0. The implementation was added to Ada URL, the high-performance URL parser now used by both Node.js and Cloudflare Workers. This move standardizes URL pattern handling across major JavaScript runtimes.

The contribution aligns with Cloudflare's work in ECMA's 55th Technical Committee, which focuses on interoperability between web-compatible runtimes. By unifying implementations in shared foundational libraries, Cloudflare aims to reduce ecosystem fragmentation and ensure consistent behavior across Node.js, Workers, Deno, and other environments.

Cloudflare also contributes to projects like V8, workerd, and wrangler, and maintains web-platform-tests conformance. The URLPattern work is part of a broader effort to upstream shared infrastructure that benefits the whole JavaScript ecosystem.

How URLPattern works

URLPattern is a WHATWG standard that provides regex-based pattern matching for URLs. It supports named parameters, wildcards, and per-component patterns across protocol, username, password, hostname, port, pathname, search, and hash. The API is included in the WinterTC Minimum Common API—a subset of web platform APIs for server-side runtimes—alongside URL and URLSearchParams.

The constructor accepts pattern strings or per-component objects. test() returns a boolean for simple matching, while exec() returns detailed results including captured groups. Internally, patterns compile once into eight specialized regular expressions, one per URL component. Subsequent matches reuse these compiled expressions.

Cloudflare Workers has supported URLPattern for years. The upstream contribution also improves the Workers implementation: it is now faster and more spec-compliant because both runtimes share the Ada-based codebase.

Basic usage:

const pattern = new URLPattern({
  pathname: '/blog/:year/:month/:slug'
});

if (pattern.test('https://example.com/blog/2025/03/urlpattern-launch')) {
  console.log('Match found!');
}

const result = pattern.exec('https://example.com/blog/2025/03/urlpattern-launch');
console.log(result.pathname.groups.year); // "2025"
console.log(result.pathname.groups.month); // "03"
console.log(result.pathname.groups.slug); // "urlpattern-launch"

Spec fixes along the way

During implementation, inconsistencies emerged between the URLPattern specification and the web-platform-tests maintained by browser vendors. Two problem areas were:

  • URLs with non-special protocols (opaque-paths)
  • URLs with invalid characters in hostnames
const pattern = new URL({ "hostname": "bad\nhostname" });
const matched = pattern.test({ "hostname": "badhostname" });
// This now returns true.

Cloudflare worked with Chromium and Safari teams to correct the specification and the associated tests. For instance, hostname components containing newline or tab characters were inconsistently handled—some implementations rejected them while others did not. The fix aligns test expectations with a corrected spec.

Where you can use it

URLPattern is now available in:

A common use case is routing in a serverless Worker. This pattern matches REST endpoints for /users and /users/:userId:

const routes = [
  new URLPattern({ pathname: '/users{/:userId}?' }),
];

export default {
  async fetch(request, env, ctx): Promise<Response> {
    const url = new URL(request.url);
    for (const route of routes) {
      const match = route.exec(url);
      if (match) {
        const { userId } = match.pathname.groups;
        if (userId) {
          return new Response(`User ID: ${userId}`);
        }
        return new Response('List of users');
      }
    }
    // No matching route found
    return new Response('Not Found', { status: 404 });
  },
} satisfies ExportedHandler<Env>;

What's next

The URLPattern contribution to Ada URL and Node.js is a baseline. Future work includes improving match performance for server-side routing scenarios and standardizing the URLPatternList proposal, which should enable faster multi-pattern matching.

Developers who hit edge cases can file issues on the workerd repository. Cloudflare also encourages other runtime maintainers to participate in web-platform-tests and WinterTC to keep server-side JavaScript consistent across runtimes.