URLPattern Routes Without Regex Drift

URLPattern routes reduce regex drift by matching already-defined URL components instead of asking each router helper to reinvent parsing, escaping, and capture semantics.

This tutorial migrates one journal router through a route inventory, named groups, precedence, base URLs, fallbacks, generation, and a hostile corpus that keeps links useful without JavaScript.

URLPattern routes start with an inventory

Treat the route table as product ownership before touching syntax. Detail, edit, search, account, and fallback states each need a responsible surface and a canonical destination.

When ownership is vague, a clever matcher merely makes the collision faster and harder to notice in review. Inside URLPattern routes, the route corpus treats URLPattern API as evidence the surface owner can contest. The route table is clearer when every pattern names the surface it is allowed to open.

List every current pathname, method-independent page identity, parameter, optional segment, redirect, and catch-all before translating syntax. Record which URLs are public contracts and which are temporary aliases so migration does not canonize accidental regex behavior.

Make a route ownership inventory answerable to the route corpus, with route ID, examples, parameters, canonical target, owner, fallback, precedence, and deprecation visible on its face. The surface owner should not need oral history to inspect it, during a contested ownership review.

• Parse: Use a trusted base
• Match: Name the groups
• Order: Expose ambiguity
• Route: Keep fallback

Let URL parsing happen once

The surface owner views this URLPattern routes decision from the angle route matching gives the route corpus. Parsing first gives later matching a stable vocabulary of URL components.

URL construction and route matching are separate phases. A trusted base resolves relative input, the URL parser separates origin, path, query, and fragment, and only then should patterns inspect the components they own. This order prevents raw-string shortcuts from assigning meaning to ambiguous slashes, escapes, or question marks.

Construct a URL against a trusted base before matching components, especially when input may be relative. Do not split on question marks, decode pieces by hand, or treat a host-looking string as a path; those shortcuts recreate the ambiguity the URL Standard resolves.

Choose the counterexample feed relative paths, encoded separators, Unicode hosts, default ports, and malformed escapes. The route corpus gives the surface owner a stop signal when different callers normalize the same input differently.

The parsing and matching contract is documented in URLPattern specification, URLPattern explainer, and WHATWG URL Standard. The URLPattern specification defines component matching and the URL Standard defines parsing before matching. The explainer clarifies design intent, but application precedence and product-level route ownership still belong to the router.

Name route groups by product meaning

Named URLPattern groups turn captures into interface fields. A slug should arrive as a slug, not as an array position whose meaning changes when another group is inserted. Decode once under an explicit rule and reject values whose decoded form crosses the route's segment boundary.

Let insert an optional segment and confirm consumers still read the same names produce the comparison case for a named-pattern catalog. Where they diverge, the surface owner has found the next route corpus edit.

Use named groups such as slug, projectId, or locale instead of positional captures whose meaning changes when a segment is inserted. Constrain the group only as tightly as the route contract requires and validate domain rules after matching. By constraining URL parsing, the route corpus makes one part of URLPattern routes legible to the surface owner. A named group is a small contract between routing and rendering code. That clarity also improves telemetry labels and incident notes.

Make precedence a visible table

Overlaps are useful evidence when they are surfaced. /journal/:slug and /journal/* may both match the same path, but the router can report both candidates and apply a reviewed priority.

Import order is a poor substitute because a harmless refactor can silently transfer ownership between screens. This is where the surface owner asks the route corpus to turn progressive enhancement into a real URLPattern routes test. Visible ambiguity is safer than invisible precedence inherited from a file layout.

The route corpus advances only after a route precedence lattice contains candidate patterns, specificity class, declared priority, selected route, ambiguity flag, and reason. Otherwise the surface owner records a blocked handoff.

Specific edit and settings routes should usually run before broad detail or catch-all routes, but the policy must be written rather than inherited from object order by accident. Detect when more than one pattern matches and either reject ambiguity or resolve it through a named precedence rule.

Separate matching from generation

Once URLPattern API moves, the surface owner no longer accepts the same URLPattern routes answer from the route corpus. Keep the weird URLs forever; they are the tests most likely to catch future drift.

Pattern tests deserve a corpus rather than three examples. Include absolute and relative URLs, base-path deployments, encoded spaces and slashes, Unicode, trailing separators, empty components, query-only changes, fragments, and hostile near misses. The corpus becomes the compatibility contract when routes evolve.

Use round-trip spaces, slashes, percent signs, Unicode, empty values, and long slugs as the stressor. If links concatenate unescaped strings independently of route definitions, the surface owner rejects the current route corpus assumption.

A matcher proves which route an incoming URL belongs to; it should not become the only way the application creates links. Keep typed link builders or canonical templates beside patterns so refactors cannot update inbound matching while emitting stale outbound URLs. Generation deserves its own encoding and canonicalization tests.

Input	Pattern	Expected	Owner
/journal/a	/journal/:slug	a	Detail
/journal/a/edit	.../edit	a	Editor
/?q=x	pathname	Root	Search
/#intro	pathname	Root	Fragment

Preserve a complete document baseline

Canonicalization belongs after ownership is known. The selected route may normalize a trailing slash or choose a canonical slug, while search and fragment state remain available to the owning surface. Redirecting during raw parsing risks erasing information before the application decides whether it matters.

Anchors and server routes remain the durable path; URLPattern can enhance client routing only when the browser and application support it. Feature detection should select a tested fallback rather than blocking navigation or shipping a second inconsistent parser. Use the route corpus to expose what route matching says about the URLPattern routes default owned by the surface owner. A canonical URL should preserve meaning, not simply produce a tidier string.

Once navigate with scripting disabled and with URLPattern deliberately unavailable is reproducible, add the difference to a progressive routing matrix. The route corpus becomes a debugging surface the surface owner can share. Fallback navigation must preserve focus, history, and scroll expectations.

Treat query and hash as separate decisions

A pathname route may own the document while search parameters own filters and the fragment owns an in-page target. Match only the components needed for routing, then parse query values with their own multiplicity and default rules instead of embedding product state in one giant pattern. The surface owner gets an explicit URLPattern routes control when the route corpus names URL parsing. One corpus lets server rendering and client enhancement disagree loudly during development.

Server and browser routers should consume the same route definitions and fixture expectations even when their rendering work differs. Parity includes decoded groups, precedence, base paths, and canonical destinations. A hydration mismatch is often a route-contract mismatch wearing a rendering symptom.

Bind pathname owner, search schema, fragment behavior, canonicalization, persistence, and analytics identity to a URL component responsibility map for the life of the decision. That is what makes the route corpus reviewable by the surface owner later.

1. 1Parse

   Use a trusted base

2. 2Match

   Name the groups

3. 3Order

   Expose ambiguity

4. 4Route

   Keep fallback

Test a hostile route corpus

Intentionally mutate each accepted URL one component at a time and require intentional outcomes. The route corpus has revealed its own limit if tests exercise only hand-picked happy paths, and the surface owner owns the repair.

Enhancement works best when anchors remain honest documents. The server returns the canonical page; the browser intercepts only routes it recognizes and can render safely.

Unknown patterns, external origins, downloads, and modified clicks continue through normal navigation instead of entering a half-supported client state. Unless progressive enhancement survives the hard case, the surface owner regards the route corpus's URLPattern routes evidence as partial. Fallback navigation is part of resilience, not evidence that enhancement failed.

A useful suite contains successes, near misses, ambiguous candidates, malformed URLs, encoded delimiters, trailing slash variants, bases, reserved names, and international text. Keep expected route IDs and group values as data so engine or specification changes produce a reviewable diff.

Route ownership stays consistent with URL product architecture, Navigation API vs History API, CSS scroll-state queries, and cancellable fetch pipelines. Durable URLs, navigation ownership, scroll-state behavior, and cancellation all consume route identity differently. Keep matching narrow so those downstream systems receive one canonical route and parameter record.

The minimal corpus accepts one canonical detail route while rejecting nested and malformed near matches.

Runnable artifact — urlpattern-route-corpus.test.mjs

import assert from "node:assert/strict";
const routes=[{id:"edit",priority:30,pattern:new URLPattern({pathname:"/journal/:slug/edit"})},{id:"detail",priority:20,pattern:new URLPattern({pathname:"/journal/:slug"})},{id:"journal-catch",priority:10,pattern:new URLPattern({pathname:"/journal/*"})}];
const match=input=>{const url=new URL(input,"https://jp.test"),candidates=routes.flatMap(route=>{const hit=route.pattern.exec(url);return hit?[{...route,groups:hit.pathname.groups}]:[]}).sort((a,b)=>b.priority-a.priority);if(!candidates.length)return null;const raw=candidates[0].groups.slug;if(raw&&decodeURIComponent(raw).includes("/"))return null;return{id:candidates[0].id,slug:raw?decodeURIComponent(raw):null,candidates:candidates.map(x=>x.id)}};
assert.deepEqual(match("/journal/urlpattern-routes"),{id:"detail",slug:"urlpattern-routes",candidates:["detail","journal-catch"]});
assert.deepEqual(match("https://jp.test/journal/hello%20world/edit").id,"edit");assert.equal(match("/journal/a%2Fb"),null);assert.equal(match("//other.test/journal/x").id,"detail");
console.log("PASS: route corpus preserves ownership");

Run node urlpattern-route-corpus.test.mjs. Expected receipt: PASS: route corpus preserves ownership.

Release with URL migration evidence

Ship the inventory, pattern catalog, precedence table, round-trip builders, redirects, sitemap diff, analytics mapping, and fallback test together. Monitor unmatched and multiply matched URLs after launch without logging sensitive query content.

The final URLPattern routes check asks the route corpus to make URLPattern API reproducible for the surface owner. Sanitized route decisions reveal drift without turning URLs into an analytics liability.

Route observability should name decisions, not collect whole URLs indiscriminately. Record route ID, matched pattern, candidate set, redirect reason, sanitized group shape, and fallback outcome. That is enough to detect precedence drift while keeping sensitive query values and user fragments out of telemetry.

The surface owner releases the route corpus only when a route migration receipt agrees with a run that can shadow both matchers on sampled safe paths before switching ownership. A mismatch remains an open decision, before the next routing release reaches production.

Use URLPattern routes to make component-aware matching inspectable, while keeping route generation, precedence, authorization, and document fallback explicit. Reopen the corpus whenever a route, base URL, encoding rule, browser implementation, or deployment prefix changes.