Next.js next/cache TypeScript Bug Investigation

A focused investigation into a TypeScript autocomplete issue affecting the generated types for next/cache.

My role covered investigation, regression analysis, a proposed direction, and independent verification of the revised implementation.

After Next.js type generation ran, every export from next/cache appeared twice in editor autocomplete. The duplicate suggestions added noise to a core API surface and indicated that two competing type sources were being resolved.

The generated ambient module declaration for next/cache was shadowing the package types. That declaration caused the editor to see the same exports through both the generated declaration and the package definition.

The initial proposed fix removed the duplicate autocomplete entries, but it also restored a catch-all overload. As a result, invalid cache profile names were accepted and the API lost an important type-safety constraint.

I reproduced and investigated the duplication, reviewed the initial change for regressions, identified the invalid-profile type-safety gap, proposed using CacheLifeProfiles to preserve typed profile names, and independently verified the revised implementation. The final implementation was authored and merged by another contributor.

The final behavior was checked with 65 assertions covering the corrected autocomplete surface and the type constraints around cache profile names.

The revised fix retained the removal of duplicate next/cache autocomplete suggestions while preserving type safety through CacheLifeProfiles.

The fix was merged into Next.js canary on September 11, 2026.