Release

What's Changed

CLI

• A new next internal upload-trace subcommand has been added that uploads CPU profiles from .next-profiles/ and Turbopack trace files to Vercel Blob storage, with chunked streaming uploads and a progress bar. The command accepts an optional directory argument and validates file headers ({"nodes": for .cpuprofile, TRACEv0 for Turbopack traces) before uploading.
• A new --internal-trace flag has been added to next build and next dev, enabling Turbopack's internal trace output during those commands.
• CPU profiles written by --experimental-cpu-prof are now saved to .next-profiles/ instead of .next/cpu-profiles/, consolidating profiling artifacts alongside Turbopack traces in a single directory.

Build Output

• The build tree view now correctly omits the route symbol (e.g. ●, ◐) from parent rows that represent grouped Static Site Generation routes — the symbol was previously duplicated on the parent when it should only appear on the individual child paths below it.
• The build output now distinguishes between fully static routes and PPR (Partial Prerendering) routes within getStaticProps-based grouped outputs, allowing each child path to carry its own accurate rendering symbol.

Experimental APIs

• A new experimental.unstableIO config flag has been added, gating the unstable_io() API exported from next/cache. This API is intended for advanced use cases involving IO access within the App Router render lifecycle.

Route Handlers

• Fixed a race condition in App Route module initialization that caused devRequestTimingInternalsEnd to be undefined in some cases; also resolved a related Turbopack HMR issue where server-side module state was not re-initialized correctly on hot reload. Top-level await in route handlers is now properly supported.

TypeScript / Type Generation

• Next.js now generates types for root layout params (dynamic root segments) into next-env.d.ts during both build and next typegen, enabling accurate TypeScript types for params passed to the root layout without manual declaration.

Turbopack: Path Prefix vs. Immutable Token

• Turbopack switched its internal asset URL strategy from an immutable content-hash token to a path-prefix-based scheme, affecting how client references and asset manifests are constructed. This change touches the client context, edge context, server context, and client reference manifest generation.

Turbopack: Backend Reliability

• Fixed a race condition in turbo-tasks-backend where two threads could simultaneously attempt to restore the same task's persisted data, leading to duplicate work or inconsistent state. Restoration is now gated with per-category meta_restoring/data_restoring flags and an Event-based wait primitive so the second thread blocks until the first finishes.
• Storage initialization for new tasks now happens before the task ID is made visible in the task cache, eliminating a window where another thread could read an uninitialized task ID.
• EventListener gained a synchronous wait() method for use in non-async backend operation contexts.

Turbopack: Performance

• The get_compilation_issues MCP tool now uses the whole_app_module_graph when computing issues, avoiding redundant graph traversals.
• turbo-persistence switched the is_empty() check to an AtomicBool to reduce lock contention on hot paths.
• Internal data tracking for persistence was restructured to reduce overhead when collecting task data for storage.

Turbopack: Observability

• Turbopack trace files are now written to .next-profiles/ (previously a different location), aligning with the CPU profile output directory.
• Family names were added to many internal tracing spans in turbo-persistence and turbo-tasks-backend, improving trace readability in profilers.
• The sst_inspect diagnostic tool now correctly handles CURRENT pointer files and stale SST files when inspecting the persistence database.

next-routing Package

• The next-routing library received significant updates to middleware matching logic and App Router request URL normalization, including expanded test coverage for captures, i18n route resolution, redirects, and full route resolution scenarios.

unstable_getResponseFromNextConfig (Testing Utilities)

• Function-typed config values (e.g., headers, rewrites returning functions) are now correctly resolved before being applied in unstable_getResponseFromNextConfig, fixing cases where such configs were silently ignored during testing.

React

• Bundled React was updated from 74568e86 (2026-03-28) to 404b38c7 (2026-04-08).

Error Messages & Documentation

• Documentation links in runtime error messages were updated from /docs/canary/ paths to stable /docs/ paths, ensuring users land on current documentation rather than canary-only pages.
• The blocking-route error message now explicitly mentions params and searchParams as common causes, improving discoverability for the most frequent trigger of this error.
• Documentation was added or improved for: cacheLife() (cannot be called at module scope), cacheComponents (notes PPR default), use cache (serverless runtime behavior), view-transitions (React canary requirement), and instant navigation.
• A middleware.mdx stub was added to the App Router file conventions reference to surface the deprecation notice for users searching for middleware documentation in that location.

---

This release spans v16.2.1-canary.26 through v16.2.1-canary.29, covering new internal CLI tooling for profiling, build output accuracy improvements, a new unstable_io experimental API, Turbopack reliability and performance fixes, and a React canary update.