# H3 v2 rewrites the Nuxt/Nitro HTTP layer around Web APIs — and changes route matching

H3 v2 became stable October 3 and now handles HTTP with standard Request, Response, URL and Headers across Node, Bun, Deno and Workers. Its router, middleware and response semantics have migration traps for existing v1 applications.

A small but foundational JavaScript HTTP framework has reached v2 with a web-standards rewrite. Builders must test route wildcards, forwarded-header trust and explicit response returns before migrating.

- Status: Active
- Published: 2026-10-17T14:53:34+13:00
- Updated: 2026-10-17T14:53:34+13:00
- Categories: Web Development, JavaScript, Frameworks, Developer Tools
- Tags: H3, JavaScript, Nitro, Nuxt, web standards
- Canonical HTML: https://beyondthe.news/dossiers/h3-v2-web-standards-rou3-routing-migration-stable

## What changed

H3 v2.0.1 was declared stable on October 3, 2026; v2.0.2 followed on October 7. The minimal HTTP framework used in the UnJS/Nitro ecosystem has been rewritten around the standard Web Request, Response, URL and Headers APIs, with srvx runtime adapters for Node.js and native interfaces on other platforms. It replaces createApp/createRouter with new H3(), adopts rou3 v1 route matching, changes how middleware scopes match paths, and encourages returning strings, objects, streams or Response objects instead of calling send utilities. Node.js >=20.19 is required. Its migration guide documents changes in proxy-header trust, request-body parsing, cookie handling and renamed utilities.

## Why it matters

This is a foundational server-framework change rather than a cosmetic version increment. Developers writing custom H3, Nitro or related framework handlers may rely on v1's implicit response writes, route matching or forwarded headers. Migrating blindly can break routes, middleware coverage or security assumptions, while the standards-first API can make cross-runtime deployment and testing simpler. The latest patch also includes fixes to stream error handling and response middleware.

## Standard web requests replace Node-specific event conventions

Handlers now receive event.req as a standard Request and event.url as URL, and can return a string, object, stream, Blob or Response. Headers use the native Headers interface. The same app can run on Node, Bun, Deno, Workers and service-worker-style environments through the appropriate runtime adapter. Node-specific req/res remain available only when running under Node.

## Routes and middleware scopes need explicit testing

H3 v2 uses the rou3 router. Middleware app.use('/path', handler) now matches that path only, not all descendants; use '/path/**' for subpaths. Later rou3 v1 routing changes alter '*' wildcard breadth, segment capture behaviour and route-rule keys. Test authentication guards, redirects and catch-all patterns with both expected and malformed paths.

## Response handling and forwarded-header trust change

Migrate send(event,value) to explicit return values and sendError to thrown errors. Body reading uses standard Request methods such as event.req.json(). The migration guide warns that getRequestProtocol/getRequestURL no longer trust x-forwarded-proto by default; explicit opt-in is needed only behind trusted proxies. Older utilities remain as compatibility exports in many cases, but not all.

## Stable release with a still-evolving migration guide

The maintainers marked v2.0.1 stable on October 3 and published v2.0.2 on October 7. The migration page still contains an older beta-stage notice, so prefer the stable release and current changelog for status. The v2.0.2 patch fixes Node stream-error handling, redirect reason phrases and middleware onError response propagation.

## Key details

- H3 v2.0.1 declared stable October 3, 2026; v2.0.2 released October 7.
- Web Request/Response/Headers/URL are the core primitives across runtimes.
- Node.js 20.19+ is required for Node deployments.
- new H3() replaces createApp/createRouter; rou3 v1 changes matching.
- app.use('/path') no longer covers all subpaths by default.
- Forwarded-proto trust is opt-in; explicit returns replace several send helpers.

## Builder takeaways

- Inventory H3/Nitro custom handlers and test response behaviour before migrating from v1.
- Run route and middleware security regression tests, particularly wildcard paths and nested auth scopes.
- Review reverse-proxy header trust; enable forwarded-proto handling only behind a trusted proxy.
- Replace send helpers with explicit returns and use standard Request body methods.
- Pin a tested v2 patch release and follow upstream migration notes; do not rely on the stale beta label in one documentation page.

## What to watch

- Further v2 patches affecting rou3 route matching or middleware.
- Nitro/Nuxt adoption and downstream compatibility fixes.
- Updated migration documentation removing outdated beta language.

## Uncertainties

- Benchmarks described by maintainers as faster/smaller are not independently reproduced here.
- Exact impact depends on which v1 utilities, router patterns and runtime adapters an application uses.
- Migration guide may change as v2 patches stabilise.

## Sources

- [H3 v2 stable announcement](https://h3.dev/blog/v2) — H3 maintainers · primary release · 2026-10-03T00:00:00+13:00. Stable release, Web API architecture, runtime support and performance claims.
- [H3 v1 to v2 migration guide](https://h3.dev/migration) — H3 maintainers · primary documentation · 2026-10-17T00:00:00+13:00. Explicit return, router, middleware, proxy header and API migration details; stale beta notice noted.
- [H3 upstream release history](https://github.com/h3js/h3/releases) — h3js · primary release · 2026-10-07T00:00:00+13:00. v2.0.1 stable status, v2.0.2 patch and rou3 routing change details.
- [JavaScript Weekly #806](https://javascriptweekly.com/issues/806) — JavaScript Weekly · independent specialist radar · 2026-10-13T00:00:00+13:00. Independent ecosystem discovery of H3 v2; technical claims checked against upstream.