> ## Documentation Index
> Fetch the complete documentation index at: https://docs.soundchecklive.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Next.js 16 Upgrade Notes

> Migration notes and residual checklist after upgrading Soundcheck web to Next.js 16.3 and React 19

Soundcheck web is on **Next.js 16.3.0** with **React 19.2.x**. The core version bump landed on this branch; this page tracks what is done and what remains.

## Current status

| Package | Soundcheck `web/` | Notes |
| - | - | - |
| `next` | 16.3.0 | App Router; production build uses Turbopack (Next 16 default) |
| `react` / `react-dom` | 19.2.x | Required by Next 16 App Router |
| TypeScript | 7.0.2 for Next build + `tsc`; `@typescript/typescript6` for AST guard test | TS ≥5.1 required by Next 16 |
| Node.js | 22.x in CI | ≥20.9.0 (Node 18 dropped in 16.0) |

## Completed on this branch

* [x] Bump `next@16.3.0`, React 19, and matching `@types/react*`
* [x] Remove invalid `eslint` key from `web/next.config.mjs` (`next lint` is gone; oxlint stays)
* [x] Remove unused peer blockers: `next-cloudinary`, `react-accessible-accordion`
* [x] Production build uses Turbopack (`next build`; Next 16 default)
* [x] Top-level `turbopack` config in `web/next.config.mjs` (was `experimental.turbopack`)
* [x] Removed leftover `webpack()` after Turbopack SVG/`@` alias rules covered all imports

## Residual checklist

* [x] **Async Request APIs** — no sync `cookies()` / `headers()` / `draftMode()` / server `params` / `searchParams` usages found in `web/src` at upgrade time
* [ ] **`middleware.ts` → `proxy.ts`** — do not rename while Clerk still needs Edge; validate Node/`proxy` runtime before migrating (build warns that `middleware` is deprecated)
* [x] **`revalidateTag`** — no usages found in `web/src`
* [x] **`cacheComponents` / Instant Navigations** — enabled in `web/next.config.mjs` ([ENG-577](https://linear.app/soundcheck-live/issue/ENG-577/web-evaluate-enable-nextjs-cache-components-instant-navigations)). Production `next build` is clean. Blockers were small: wrap service-console `auth()` in `<Suspense fallback={null}>` so the protected shell is not shown before platform-admin authorization, drop `export const runtime` (Cache Components rejects any `runtime` segment config), and Suspense-bound layouts that call `usePathname` / `useSearchParams`. The `AuthenticatedProviders` pathname gate uses `fallback={children}` so a postponed `usePathname()` keeps route content (or the route layout loading UI) in the PPR shell. The root layout uses a static background fallback so public `/[slug]` `useParams()` is not prerendered as that boundary's fallback. Staff app paths share `protectedAppRoutes.ts` so `/hotels`, `/assets`, and the other single-segment staff pages do not look like public org slugs. `/dev/components` is a client page so Cache Components does not SSR `useRef` there. No `instant = false` opt-outs. Prefetch is production-only (`next start` / deployed).
* [x] **SVG / `webpack()` in `next.config.mjs`** — Turbopack `resolveAlias` + `*.svg` SVGR rules cover all imports; leftover `webpack()` removed
* [x] **TypeScript** — `typescript` is now real TS 7 for Next build + `tsc`; AST guard test imports `@typescript/typescript6` for the compiler API
* [x] **Verify** — `next build` green on Turbopack with Cache Components + Partial Prefetch. Web CI Playwright e2e (Clerk-backed) remains the auth/nav gate. Optional human smoke: sign-in + org switch.

## Version-by-version reference

You can jump straight to **16.3**; intermediate minors are not required. Almost all breaking work is in **16.0**.

### 16.0 — major (Oct 2025)

Official: [blog](https://nextjs.org/blog/next-16), [upgrade guide](https://nextjs.org/docs/app/guides/upgrading/version-16).

**Breaking / removals**

* React 19 required; Node ≥20.9; TypeScript ≥5.1
* Sync Request APIs removed — must `await` `cookies()`, `headers()`, `draftMode()`, `params`, `searchParams`
* Metadata image / sitemap generators: `params` / `id` are Promises
* Turbopack is default for `next dev` and `next build`; custom `webpack()` **fails the build** unless you migrate config, pass `--webpack`, or keep Turbopack with `next build --turbopack` (ignores leftover `webpack()`)
* `experimental.turbopack` → top-level `turbopack`
* `experimental.ppr` / `experimental_ppr` / `dynamicIO` removed → `cacheComponents`
* `next lint` removed; AMP removed; runtime config APIs removed
* Parallel route slots require explicit `default.js`
* `next/image` default changes (`minimumCacheTTL`, `qualities`, `imageSizes`, local IP, max redirects, local query strings)
* Scroll no longer overrides global `scroll-behavior: smooth`

**Deprecations**

* `middleware.ts` → `proxy.ts` / export `proxy` (`proxy` is **Node.js only**; Edge needs deprecated `middleware` for now)
* `next/legacy/image`, `images.domains`
* Single-arg `revalidateTag(tag)` → `revalidateTag(tag, profile)` or `updateTag()` in Actions

**Non-breaking**

* Cache Components, React Compiler (`reactCompiler`), `updateTag()` / `refresh()`, routing/prefetch rewrite

### 16.1 — minor (Dec 2025)

[Blog](https://nextjs.org/blog/next-16-1). Additive: Turbopack FS cache for `next dev` (default on), bundle analyzer, `next dev --inspect`, transitive `serverExternalPackages`, `next upgrade`.

### 16.2 — minor (Mar 2026)

[Blog](https://nextjs.org/blog/next-16-2). Additive: faster `next dev` / rendering, adapters stable, debugging UX, `unstable_catchError` / `unstable_retry`, prefetch experimentals. Security patches through **16.2.6** are included in 16.3.

### 16.3 — minor (Aug 2026)

[Blog](https://nextjs.org/blog/next-16-3). Largest release since 16.0; **no major breakages** for apps already on 16.

**Default wins:** lower Turbopack memory, build FS cache, native Node streams SSR, agent docs / `AGENTS.md`, `catchError`, `import.meta.glob`, `next/root-params`, TS7 for typecheck in build.

**Opt-in Instant Navigations:** `cacheComponents: true` + `partialPrefetching: true` (future major default).

**Watch:** HMR path `/_next/webpack-hmr` → `/_next/hmr` if reverse proxies pin the old path.

## Remaining hot spots

| Area | Risk | Notes |
| - | - | - |
| Async Request APIs | High | Grep pages/layouts/routes still using sync access |
| `middleware.ts` + Clerk | High | Do not blindly rename to `proxy.ts` while Edge is required |
| `webpack()` in `next.config.mjs` | Done | Removed; Turbopack SVG/`@` alias rules are the sole path |
| `revalidateTag` | Medium | Add `cacheLife` profile or switch to `updateTag` |
| Images | Low | Already on `remotePatterns`; review quality / TTL defaults |
| `cacheComponents` | Done | `cacheComponents` + `partialPrefetching` on; request-time work stays behind `<Suspense>` (service-console `auth()`, client URL hooks). Do not add `'use cache'` on auth/org data. |

## Sources

* [https://nextjs.org/docs/app/guides/upgrading/version-16](https://nextjs.org/docs/app/guides/upgrading/version-16)
* [https://nextjs.org/blog/next-16](https://nextjs.org/blog/next-16)
* [https://nextjs.org/blog/next-16-1](https://nextjs.org/blog/next-16-1)
* [https://nextjs.org/blog/next-16-2](https://nextjs.org/blog/next-16-2)
* [https://nextjs.org/blog/next-16-3](https://nextjs.org/blog/next-16-3)
* [https://vercel.com/changelog/next-js-may-2026-security-release](https://vercel.com/changelog/next-js-may-2026-security-release)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.