Review a Next.js 16.3 upgrade for the webapp

[HMarzban]

Goal

Decide whether @docs.plus/webapp should leave Next 15.5.21 for 16.3.1. Land the upgrade only if the Pages Router path is safe.

Facts (2026-08-21)

• Latest Next is 16.3.1 (npm latest, published 13 August 2026). Docs · 16.3 blog · v16.3.1
• Webapp is next@15.5.21 on Pages Router. React is already ^19.2.7.
• Admin dashboard already runs next@^16.2.12 on the same Pages + React 19 stack. That is the in-repo proof that Pages works on 16.
• Webapp eslint-config-next is already ^16.2.12. Runtime and lint are skewed.
• Official 16.3 claims for “all existing apps”: dest RAM “up to 90% less”; some CI builds “5.5× faster” with Turbopack disk cache; “up to 22% more requests under load” after replacing web streams in the App Router rendering layer. Source: nextjs.org/blog/next-16-3
• Instant Navigations, Partial Prefetching, Cache Components, and the 16.2 RSC HTML claims need App Router. This repo stays on Pages. Do not count those as wins.
• Official dest/build split: next dest writes .next/dev; next build writes .next. That is the vendor fix for our shared-.next BUILD_ID clash. A lockfile still blocks two dest or two build processes. Upgrade guide
• Next 16 makes Turbopack the default for dest and build. A custom webpack config fails next build unless you pass --webpack.
• Webapp wraps config with next-pwa@5 and still has a webpack hook. That is the main friction.
• getServerSideProps is still documented on Pages in 16.3.1. No removal announced.
• 15.5 is Maintenance LTS. A 15.5 and 16.3 security patch is scheduled for 26 August 2026. July 2026 security note

What to build

A review first, then a bump. Stay on Pages Router.

1. Read the 16 upgrade guide. Run @next/codemod upgrade against the webapp only.
2. Decide next-pwa: keep with --webpack, replace, or drop. Admin has no PWA and is already on 16. Use it as the SSR template.
3. Align webapp next to 16.3.1, or to admin’s 16.2.12 first if 16.3.1 is too new. Align eslint-config-next.
4. Confirm dest writes .next/dev and that a live dest plus build:ci no longer corrupt the dest server. Update AGENTS.md if that rule changes.
5. Measure dest RSS and a cold build:ci versus 15.5.21. Do not cite the 22% App Router number as ours.
6. Walk /, a public pad, sign-in, and PWA install (if PWA stays).

Out of scope

• App Router migration.
• Instant Navigations, Cache Components, or 'use cache'.
• Bumping TypeScript 6 → 7 across the monorepo (optional later; Next 16.3 can typecheck with TS 7).
• Admin 16.2.12 → 16.3.1 unless the webapp bump proves it cheap.

Acceptance criteria

• A short verdict at the top of the PR or a follow-up comment: upgrade, wait for the 26 August patch, or stay on 15.5 LTS. Name the reason.
• If upgrading: webapp next matches a published 16.x. next dest --turbopack and next build both succeed with dest stopped first.
• next-pwa either works on 16 or is replaced or removed, with the install path re-checked.
• Pages GSSP routes still render ([...slugs], /, auth error, sitemap, robots).
• One dest-RSS or build:ci time number versus 15.5.21. Official 90% / 5.5× / 22% quotes are not a substitute.
• AGENTS.md dest-versus-build rule matches 16 behavior (.next/dev versus .next).

Blocked by

None for the review. The bump can wait for the 26 August 2026 Next security patch if the maintainer prefers a patched 16.3. Does not depend on the Bun 1.4 ticket.