compare changes

Preset Changes

• aws-amplify: Support node.js 22 and 24 runtimes (#4244)
• cloudflare: Prefer source path rather than #imports (#4247)
• vercel: Add framework info to build output config (#4475)
• vercel: Add support for node@24 (v2) (#4628)

✅ Tests

• Fix windows path handling in new tests (f6bcc4f4)
• Use memory cache storage in dev fixture to avoid flaky cache test (e98dced6)

🩹 Fixes

• types: Only strip extensions that ts retries (f3a57737)
• types: Emit auto-import paths as files, not directories (#4334)
• Respect h3 url in swr handler (#4386)
• Preserve sourcemap mappings for chunks containing user code (#4450)
• build: Count each output file once in the size report (#4569)
• vercel: Mark header-only route entries as continue (#4651)
• cloudflare: Guard nodejs_compat flag by compatibility date (#4663)
• cloudflare: Detect implicit nodejs_compat when deployConfig is false (#4667)
• cloudflare: Warn only about conflicting asset overrides (#4690)
• externals: Match string rules against windows ids (#4732)
• externals: Normalize resolved paths on windows (#4752)
• rollup: Keep import attributes in the build output (#4519)
• dev: Close upgraded sockets and resolve on worker shutdown timeout (#4671)
• openapi: Only filter undefined from array nodes (#3895)
• dev: Proxy websocket upgrades for devProxy routes with ws (#4788)
• vercel: Strip trailing slash from prerendered route overrides (#4791)
• vercel: Use SameSite=Lax for skew protection cookie (#4789)
• static: Respond with 404 when a public asset is missing on disk (#4787)
• bun: Support NITRO_BUN_IDLE_TIMEOUT=0 (#4190)
• vercel: Enable ISR passQuery when allowQuery is set (#4790)
• prepare: Keep public assets inside output dir when cleaning (#4798)
• task: Support dev worker listening on a unix socket or named pipe (#4797)
• node, deno: Support PORT=0 for random port assignment (#4796)
• bun: Use hostname option for Bun.serve (#4795)
• prerender: Only refuse .. as a whole path segment (#4794)
• cloudflare: Fix baseURL traversal for wrangler assets dir (#4793)
• cloudflare: Use pathe for POSIX relative paths in wrangler.json (v2) (#4801)

📖 Documentation

• Workaround for search-and-replace issues (#3078)

📦 Build

• Resolve subpath types under nodenext (#4757)

🌊 Types

• Widen RollupConfig.plugins to accept rolldown-typed plugins (#4484)
• Add missing wrangler observability types (#4742)

🔥 Performance

• dev: Cache sourcemap consumer per bundle in error handler (#4786)

❤️ Contributors

• Liang Xu
• Pooya Parsa (@pi0)
• Ilya Semenov (@IlyaSemenov)
• Kricsleo (@kricsleo)
• Nestor Vera
• Daniel Roe (@danielroe)
• Leonid G. agantelin@gmail.com
• Rocky
• Paul
• Harlan Wilton
• Agustin18
• Rihan Arfan (@RihanArfan)
• Jonas Thelemann
• Maxim Lepekha
• Adrien Foulon
• Abdul Rauf (@armujahid)

Many of new improvements are from major dependency upgrades (h3, srvx, rou3, ocache, db0, env-runner, unctx and unwasm) plus the work in Nitro to adopt them. The sections below group the changes by what they mean for your app.

🚀 What’s new

🧭 Routing and route rules

Nitro migrated to the new route rules engine from h3, backed by rou3 v0.9. See the Nitro routing guide and h3 route rules guide. (#4411)

• Rules are matched on the canonical path, with sibling routes ordered by specificity. (#4396)
• GET routes automatically answer HEAD requests.
• New cors rule replaces manual CORS wiring: { "/api/**": { cors: true } }.
• basicAuth route rules are replaced by middleware (see After you upgrade).

💾 Caching

defineCachedHandler, defineCachedFunction and cache route rules now run on ocache v0.3 (up from 0.1), which brings safer defaults, bounded memory and several new capabilities. Please review your caching configuration — defaults changed. See Review your caching configuration and the Nitro caching guide.

🗄️ Database

Nitro now uses db0 v0.4. Database client libraries are passed explicitly to connectors; Nitro handles this for configured connectors and prompts to install what is missing. New in this line: neon, prisma and libsql-core connectors, Kysely integration, database capabilities metadata, and tracing channel support. See the Nitro database guide, db0 connectors, and db0 integrations.

🔌 WebSockets

WebSocket support moves to crossws 0.4.12 (from 0.4.6), which adds a batch of features usable from Nitro WebSocket handlers. See the Nitro WebSocket guide.

• Liveness: universal idleTimeout to detect half-open connections, application-level ping/pong hooks and peer.ping(). (#201, #202)
• Backpressure: peer.bufferedAmount (docs) and opt-in subprotocol negotiation. (#195, #203)
• Pub/sub: a sync backplane to share channels across instances (docs), plus auth and context support. (#192, #112)

🔭 Observability and tracing

• Native platform traces: Nitro sends spans to Vercel session traces and Cloudflare Workers Observability without bundling the OpenTelemetry SDK. (#4355, #4413)
• Built-in tracing logger: enable tracingChannel and experimental.tracingLogger to log completed h3, srvx, unstorage, db0 and other spans in development and production — without additional dependencies. (#4406)

🔒 Security

• h3 has undergone several rounds of security hardening audits (path normalization, forwarded headers, host header handling, cookies, CORS, basic auth, JSON-RPC, session sealing).
• Development task endpoints (/_nitro/tasks and /_nitro/tasks/:name) now accept only local requests. This prevents remote clients with access to the dev server from listing or invoking tasks. (#4389)
• Cached responses no longer replay cookies by default.
• Better static file responses: conditional requests with ETag and Last-Modified, byte ranges, optional Cache-Control, and additional path-traversal hardening.

⚡ Faster and more reliable

• Improved alias resolution, development sourcemaps, request middleware, and logging.
• Development worker reloads are serialized and cleanly awaited, stale module caches are cleared, (vite) aliases apply in the correct order, base paths are respected, and ?import requests remain handled by Vite.
• Static presets no longer create an unnecessary server bundle.

📁 Import any file as bytes or text

In server bundle: (#4431)

  import logo from "./logo.png" with { type: "bytes" }; // Uint8Array
  import readme from "./README.md" with { type: "text" }; // string

📦 No more peer dependencies

Nitro no longer has any peer dependencies. Features that need an extra package (a builder, a preset, a storage driver, a database connector) resolve it from your project, and Nitro prompts to install anything missing. In CI, missing packages are installed automatically. Existing projects need no changes when the required packages are already installed. (#4542, #4543)

Nitro also validates the version of what it finds and warns when an installed package is outside the supported range. Supported builders are vite@^7 || ^8, rollup@^4 and rolldown@>=1.0.0. (87219b2)

Leaner install

Alongside dropping peer dependencies, several packages were removed from Nitro entirely: tsconfck (replaced by get-tsconfig), magic-string, uncrypto, serve-placeholder, edge-runtime, @types/http-proxy and @types/node-fetch. ofetch is no longer a runtime dependency, and rou3 is now a direct dependency instead of being pulled in indirectly.

☁️ Presets

• Cloudflare: local development now uses Miniflare/workerd directly, with bindings available on the request event. Nitro offers to install miniflare when first needed. See the Nitro Cloudflare guide. (#4338)
• Vercel: set vercel.immutableStaticFiles: true to emit content-hashed static files with immutable caching. See the Nitro Vercel guide. (#4432)
• Netlify Edge: keeps dynamic imports lazy, reducing cold-start work for lazy handlers and deferred WASM initialization. (#4525)

⚠️ Migration

Routing

• Replace basicAuth route rules with middleware.

  import { defineHandler } from "nitro";
  import { basicAuth } from "nitro/h3";
  
  export default defineHandler({
    middleware: [basicAuth({ username: "admin", password: "supersecret" })],
    handler: (event) => `Hello, ${event.context.basicAuth?.username}!`,
  });

  To protect multiple routes, register route-scoped middleware or add it under middleware/.

• Use the new cors rule where needed: { "/api/**": { cors: true } }.

• Update renamed types when convenient: NitroRouteConfig and NitroRouteRules are deprecated aliases for RouteRuleConfig and NormalizedRouteRules. The old names are still exported from nitro/types.

Review your caching configuration

The upgrade from ocache 0.1 to 0.3 introduces safer defaults for defineCachedHandler, defineCachedFunction, and cache route rules:

• swr now defaults to false, so expired entries are refreshed before returning. Set swr: true to keep background revalidation. The swr route-rule shortcut already does this.
• Query parameters are ignored by default. Set allowQuery: true or list the parameters that should affect the cache key.
• Cookies are removed from cached requests and responses unless listed in allowCookies; responses containing Set-Cookie are not cached.
• GET and HEAD now use separate cache entries.
• Cache keys now include the request authority, and undeclared request headers are hidden from handlers.
• Cache resolution has a new 30-second timeout (maxResolveTime), and memory storage is limited by bytes.

See the ocache migration guide for details.

📦 Major dependency updates

h3

• **New ...

compare changes

🚀 Enhancements

• prerender: Run prerenderer in isolate worker (#4326)
• vite: Use explicit module graph for service entries (#4327)

Preset Changes

• vercel: Support websocket upgrades (internal testing) (#4317)

🩹 Fixes

• Try to resolve server entry also from server dir (#4313)
• runtime: Avoid std-env in warning stub (#4296)
• vite: Force resolve nitro/ imports from service envs (#4324)
• vite: Inherit renderer for prerender build (#4325)
• vite, prerender: Use shared virtuals (#4328)
• build: Add buildDir to noExternals if inside node_modules (#4329)
• types: Emit auto-import paths as files, not directories (#4333)
• vite: Propagate service fetch errors in dev to match production (#4335)

📖 Documentation

• Fix inline escaing (#4312)

❤️ Contributors

• Pooya Parsa (@pi0)
• Daniel Roe (@danielroe)
• Andrew Barba (@AndrewBarba)
• Max (@onmax)
• Eduardo San Martin Morote (@posva)

compare changes

🚀 Enhancements

• build: Support custom framework preview/deploy commands (#4293)
• config: Add defaultPreset to customize the fallback preset (#4299)

🩹 Fixes

• types: Only strip extensions that ts retries (#4297)

📖 Documentation

• Fix quick-start preview image (#4307)
• Fix typo in path to H3 v2 docs (#4301)

❤️ Contributors

• Pooya Parsa (@pi0)
• Matvey (@matrv)
• Ulrich Stark (@ulrichstark)
• Daniel Roe (@danielroe)

compare changes

🚀 Enhancements

• Wrap route handlers with tracing at build time (#4240)
• vercel: Support queues in local dev (#4264)

🔥 Performance

• Use VFS for nitro app dynamic code (#4251)

🩹 Fixes

• vite: Route extensionless URLs matching a nitro route to nitro under asset sec-fetch-dest (7d49dcae)
• vite: Ignore query-string extensions when detecting asset requests (08f2ec69)
• build: Externalize packages with import-only exports (d7a34477)
• vite: Pass correct root config in builder (6c9007c0)
• vite: Resolve vite dep from user dir (e770268d)
• vite: Allow global prod builds with npx (#4260)
• vite: Route asset-extensioned URLs matching explicit routes to nitro (#4272)

💅 Refactors

• Replace inlined types with upstream deps (#4239)

📖 Documentation

• Correct tsconfig paths alias in vite-ssr-tsr-react example (#4271)

Preset Changes

• aws-amplify: Support node.js 24 runtime (#4245)

❤️ Contributors

• Rihan Arfan (@RihanArfan)
• Pooya Parsa (@pi0)
• Sihan (Echo) Zhang (@ZDSJdeJT)
• Abdelrahman Awad (@logaretm)
• Abdul Rauf (@armujahid)

compare changes

🚀 Enhancements

• tracing: Enable tracing channels for unstorage (#4226)

🩹 Fixes

• Accept ipv4-mapped ipv6 loopback in vfs handler (#4212)
• route-rules: Reject out-of-scope requests (#4222)
• route-rules: Prevent open redirect via protocol-relative url bypass (#4236)
• vite: Route browser asset loads to vite when sec-fetch-dest is absent (#4238)

💅 Refactors

• Use built-in escapeRegExp util (#4109)

📖 Documentation

• cache: Add invalidation usage (#4216)
• Improve jsdocs (#4199)

📦 Build

• Shim oxc-parser via rolldown/utils (#4237)

🌊 Types

• vite: Make experimental.vite type optional (#4225)

Preset Changes

• cloudflare: Add missing types for cloudflare.wrangler.observability.traces (#4220)
• vercel: Enable shouldAddSourcemapSupport when sourcemap is enabled (#4232)

❤️ Contributors

• Pooya Parsa (@pi0)
• Rihan Arfan (@RihanArfan)
• Ofer Shapira (@ofershap)
• Abdelrahman Awad (@logaretm)
• Sōta (@sotasan)
• Btea (@btea)
• Restent Ou (@gxres042)

compare changes

🚀 Enhancements

• Add version meta (#4194)

🩹 Fixes

• route-rules: Reject out-of-scope requests (#4223)
• route-rules: Prevent open redirect via protocol-relative url bypass (8d6bfb0b)

🏡 Chore

❤️ Contributors

• Pooya Parsa (@pi0)
• Rihan Arfan (@RihanArfan)

compare changes

✨ Highlights

Experimental tracing channels. Nitro now has built-in tracing channel support for tracing request spans.

Smarter dependency tracing. traceDeps picks up full-trace mode and custom trace options, backed by upstream nf3 improvements — a growing native-packages DB and automatic detection of optional dependencies mean fewer missing binaries in production bundles.

H3 v2 updates Stricter streaming body-size checks, cookie utils with RFC 6265bis compliance, and a handful of request normalization fixes — including protection against path traversal via double-encoded segments.

Ecosystem upgrades. ocache now has cache invalidation via handler.invalidate() and multi-tier cache support, and unstorage now proactively flushes expired memory entries instead of waiting for the next access both available for Nitro cache and KV storage.

Vercel preset supports queues and per-route function config. You can now use Vercel queues in Nitro deployments to process messages asynchronously (docs), and override function config on a per-route basis(#4124) handy when a single route needs more memory or a longer timeout than the rest of your app.

Deploy to Tencent EdgeOne Pages. Deploy Nitro apps to EdgeOne Pages (docs)

OpenAPI and WebSocket docs. New guides for OpenAPI and WebSocket.

🚀 Enhancements

• vercel: Allow overriding function config per route (#4124)
• traceDeps: Support full-trace and custom trace options (#4175)
• Add version meta to Nitro instance (#4193)
• openapi: Add swagger ui config (#4185)
• vercel: Support queues (#4127)
• Experimental built-in tracing channel support (#4001)
• Add edgeone-pages preset with build output api v3 (#4170) (docs)

🩹 Fixes

• cloudflare-dev: Match getPlatformProxy dev behaviour with production runtime (#4102)
• Use rolldown/utils and disable additional tsconfig parsing (#4111)
• route-meta: Unique handlers by hash + method + route (#4119)
• route-meta: Deduplicate routing-meta imports by _importHash only (#4120)
• Guard against createRequire(import.meta.url) in bundled output (#4133)
• cloudflare: Set rolldown platform to node when nodeCompat is active (#4138)
• cloudflare: Add worker to default conditions (9054dee6)
• vite: Match service entry chunk by facadeModuleId (#4123)
• vite: Handle dotted Nitro routes under baseURL in dev (#4108)
• vite: Proxy nitro/* imports from service environments (#4152)
• runtime: Avoid infinite recursion in fetch for external URLs (#4153)
• build: ⚠️ Remove custom moduleSideEffects config (#4164)
• config: Treat swr: 0 as a valid cache value (#4167)
• Exclude wrangler from generated NitroRuntimeConfig type (#4149)
• Allow to run tasks via nitro cli (#4188)
• deno-deploy: Add req.ip (#4196)
• Always run basicAuth route rule first (#4204)

💅 Refactors

• Improve nitro/tsconfig preset (52472769)
• Remove experimental.tsconfigPaths (#4112)

📖 Documentation

• Correct routing example code (#3937)
• Fix typos (#4169)
• Remove import in auto-imports example (#4150)
• Use cleaner imports in examples and add read more links to config (#4200)
• Add openapi guide (#4198)
• Add websocket guide (#4197)

📦 Build

• Move docs to dist/docs (9ce219ca)

Preset Changes

• vercel: Support max value on maxDuration types (#4172)

⚠️ Breaking Changes

• build: ⚠️ Remove custom moduleSideEffects config (#4164)

🌱 Ecosystem

Notable upstream changes rolled in via dependency updates:

h3 rc.16 → rc.20

• Add redirectBack utility (#1329)
• cors: Preserve CORS headers on error responses (#1352)
• sse: Mark writer as closed on write failure (#1322); sanitize carriage returns in event stream (79cabe3)
• request: Include Allow header in 405 response (#1314)
• mount: Normalize percent-encoded pathname in requestWithBaseURL (0295f90); enforce path segment boundary in startsWith (7ccc9e2)
• static: Prevent path traversal via double-encoded dot segments (8e9993f)
• utils: Prevent open redirect via protocol-relative path in redirectBack() (459a1c6)
• cookie: Prevent unbounded chunked cookie count (399257c)
• body: Enforce stream-based body size check regardless of content-length (708a3aa)
• Upgrade cookie-es to v3 (9d244a7)

crossws 0.4.5

WebSocket Proxy integration will be added as a nitro route rule in next releases. You can directly use it in meanwhile from crossws package.

• New createWebSocketProxy util (#184)
• New fromNodeUpgradeHandler util + socket.io support (#185)
• New bunny adapter (#179)
• node: Do not url-encode upgrade response headers (ffbed40)

srvx 0.11.9 → 0.11.15

• node: Handle error and abort propagation for piped streams (77f879b)
• node: Fallback to socket address on invalid Host header (#192)
• node: Combine duplicate headers in entries() iterator (4ed7453)
• node: Improve pipeBody stability and performance (5e731ef, 4051f22)
• url: Deopt absolute URIs in FastURL (de0d699)
• node: Handle EADDRINUSE port conflict on serve (#197)
• node/web: Do not swallow getReader errors (#199)

unstorage 2.0.0-alpha.7

• memory: Proactively flush expired entries after ttl (#759)
• fs: Resolve ignore pattern matching for dot-prefix paths (#751)

ocache 0.1.2 → 0.1.4

• Respect staleMaxAge (8915db3) and zero ttl (#5)
• cache: Add resolveCacheKey and .resolveKey() (#6)
• storage: Nullish set deletes entry (71d5f11)
• Multi-tier cache base (#7)
• cache: Add handler.invalidate() (#8); evict stale entry on SWR revalidation failure (#9)
• storage: Proactively flush expired memory entries (#10)
• cache: Skip writing to lower tiers on multi-tier cache hit (4fe0de7)

nf3 0.3.11 → 0.3.16

• Add fullTraceInclude option (#4)
• plugin: Use traceInclude ([#2...

compare changes

📦 Dependency Updates

compare changes

🩹 Fixes

• prerender: Skip writing routes with .. or outside of public dir (81f76800)
• prerender: Mark invalid routes as skipped (9cb795c7)

📖 Documentation

• Fix icon assets (#4022)

Preset Changes

• vercel: Add types and docs for isr.exposeErrBody (f7753152)

❤️ Contributors

• Pooya Parsa (@pi0)
• Restent Ou (@gxres042)
• Kricsleo (@kricsleo)