npm / h3

h3

What changed in h3 1 to 2, from its official release notes, upgrade guides and advisories. Sources checked 2026-10-20.

28 breaking6 security25 deprecations2 new APIs and options2 behavior and defaults1 fixes and other

See which of these apply to your code, ranked, in your agent:

npx @unstale/cli init

@unstale/cli 0.2.0 on npm

h3 259 changes

Breaking changes 28

The App type export migrates to H3.
2.0.0upgrade guide
app.resolve(path) has been removed.
2.0.0upgrade guide
app.use("/path", handler) now matches only /path; use /path/** to match subpaths.
2.0.0upgrade guide
Array paths and arrays of handlers are no longer supported; use multiple app.use() calls.
2.0.0upgrade guide
The AppOptions type export migrates to H3Config.
2.0.0upgrade guide
createEvent was removed; use the Node.js adapter toNodeHandler(app).
2.0.0upgrade guide
CreateRouterOptions migrates to RouterOptions.
2.0.0upgrade guide
Lazy handlers must be wrapped with defineLazyEventHandler instead of passing a factory directly to app.use.
2.0.0upgrade guide
H3 v2 is ESM-only; latest Node.js versions can still load it with require("h3") through require(esm).
2.0.0upgrade guide
Handler event.path now includes the full path without omitting prefixes; withBase can create a prefixed app.
2.0.0upgrade guide
event.web is renamed to event.req, which is an instance of the web Request interface.
2.0.0upgrade guide
getRequestProtocol no longer trusts x-forwarded-proto by default; opt in with xForwardedProto behind a trusted proxy or CDN.
2.0.0upgrade guide
H3Headers migrates to the native Headers type.
2.0.0upgrade guide
H3Response migrates to the native Response type.
2.0.0upgrade guide
H3 uses standard web Headers for utilities, and header values are always strings.
2.0.0upgrade guide
isEventHandler was removed; any function can be an event handler.
2.0.0upgrade guide
Replace sendIterable(event, value) with return iterable(value).
2.0.0upgrade guide
MIMES has been removed.
2.0.0upgrade guide
Replace sendNoContent(event) or return null with return noContent().
2.0.0upgrade guide
H3 v2 requires Node.js >= 20.19.
2.0.0upgrade guide
The NodeListener type export migrates to NodeHandler.
2.0.0upgrade guide
Replace sendProxy(event, target) with return proxy(event, target).
2.0.0upgrade guide
Replace sendRedirect(event, location, code) with return redirect(location, code).
2.0.0upgrade guide
Body utilities return empty values instead of throwing when a request has no body, such as for GET requests.
2.0.0upgrade guide
Handlers should explicitly return response bodies or throw errors; H3 detects returned text, JSON, streams, and web Responses.
2.0.0upgrade guide
RouteNode migrates to RouterEntry.
2.0.0upgrade guide
A router handler that returns no response now produces a simple 200 with empty content.
2.0.0upgrade guide
The signature changes from router.add(path, method) to router.add(method, path).
2.0.0upgrade guide

Security 1

Native request.json and readBody no longer use destr; filter and sanitize user data to avoid prototype poisoning.
2.0.0upgrade guide

Deprecations 25

Response header append utilities are deprecated; use event.res.headers.append(name, value).
2.0.0upgrade guide
createApp and createRouter are deprecated; migrate to new H3().
2.0.0upgrade guide
createError and H3Error are deprecated; migrate to HTTPError.
2.0.0upgrade guide
createEventStream is deprecated; migrate to new EventStream(event).
2.0.0upgrade guide
eventHandler and defineEventHandler are deprecated; migrate to defineHandler or use a function directly.
2.0.0upgrade guide
defineNodeListener is deprecated; migrate to defineNodeHandler.
2.0.0upgrade guide
event.headers is deprecated; use event.req.headers.
2.0.0upgrade guide
event.method is deprecated; use event.req.method.
2.0.0upgrade guide
event.path is deprecated; use event.url.pathname + event.url.search.
2.0.0upgrade guide
fromNodeMiddleware is deprecated; migrate to fromNodeHandler.
2.0.0upgrade guide
getHeader and getRequestHeader are deprecated; use event.req.headers.get(name).
2.0.0upgrade guide
getHeaders and getRequestHeaders are deprecated; use Object.fromEntries(event.req.headers.entries()).
2.0.0upgrade guide
getMethod is deprecated; use event.req.method.
2.0.0upgrade guide
getRequestPath is deprecated; use event.url.pathname.
2.0.0upgrade guide
getResponseHeader and getResponseHeaders are deprecated; use event.res.headers.get(name).
2.0.0upgrade guide
Response status utilities are deprecated; use event.res.status and event.res.statusText.
2.0.0upgrade guide
isError is deprecated; migrate to HTTPError.isError.
2.0.0upgrade guide
lazyEventHandler is deprecated; migrate to defineLazyEventHandler.
2.0.0upgrade guide
Form-data body utilities are deprecated; use event.req.formData().
2.0.0upgrade guide
readRawBody is deprecated; use event.req.text() or event.req.arrayBuffer().
2.0.0upgrade guide
removeResponseHeader and clearResponseHeaders are deprecated; use event.res.headers.delete(name).
2.0.0upgrade guide
router.use(path, handler) is deprecated; use router.all(path, handler) instead.
2.0.0upgrade guide
Response header setter utilities are deprecated; use event.res.headers.set(name, value).
2.0.0upgrade guide
toNodeListener is deprecated; migrate to toNodeHandler.
2.0.0upgrade guide
useBase is deprecated; migrate to withBase.
2.0.0upgrade guide

New APIs and options 2

The router is integrated into H3; use new H3() instead of createApp() and createRouter().
2.0.0upgrade guide
readBody parses JSON or URL-encoded requests using JSON.parse or URLSearchParams.
2.0.0upgrade guide

Behavior and default changes 2

Native event.node.{req,res} is only available when the server runs in the Node.js runtime.
2.0.0upgrade guide
Middleware without a response lets later handlers run; if none respond, H3 returns a 404.
2.0.0upgrade guide

Fixes and other changes 1

Check handleCors's return value and return early when it handled the request.
2.0.0upgrade guide

h3 15 changes

Security 5

h3: Double Decoding in serveStatic Bypasses resolveDotSegments Path Traversal Protection via %252e%252e
1.15.9security advisory
h3: SSE Event Injection via Unsanitized Carriage Return (\r) in EventStream Data and Comment Fields (Bypass of CVE Fix)
1.15.9security advisory
h3 has a Path Traversal via Percent-Encoded Dot Segments in serveStatic Allows Arbitrary File Read
1.15.6security advisory
h3 has a Server-Sent Events Injection via Unsanitized Newlines in Event Stream Fields
1.15.6security advisory
h3 v1 has Request Smuggling (TE.TE) issue
1.15.5security advisory