Spike: evaluate Next.js 16 upgrade path for findable-ui and consumers

[NoopDog]

Summary

Next.js 16 (released 2025-10-21) is now latest on npm (16.2.4). findable-ui currently pins next ^15.5.13 as a peer dep. This spike scopes what a v16 upgrade costs for this library and for each consuming app (data-browser, ncpi-dataset-catalog, hca-atlas-tracker, etc.) and proposes a phased upgrade plan.

Current state (audit)

• Peer deps: next ^15.5.13, react ^19.2.3, Node 22.12.0
• Pages Router APIs in library: next/router, GetStaticProps*, GetStaticPaths* (in src/utils/mdx/staticGeneration/)
• MDX: next-mdx-remote/serialize v5 — runtime serializer consumed via getStaticProps pattern
• No App Router RSC usage: no "use client"/"use server", no next/headers, no next/cookies
• Router-agnostic imports in use: next/link, next/head, next/image, usePathname, useSearchParams, ReadonlyURLSearchParams

Goals

1. Go/no-go recommendation with rough effort estimate (S/M/L per consumer).
2. Identify blockers that need upstream fixes before we can bump the peer range.
3. Draft a phased rollout plan: library bump → per-consumer upgrades.

Deliverables

• Compatibility matrix: findable-ui features × Next 16 changes.
• Per-consumer impact notes (router type, MDX use, image/middleware use).
• Proposed PR sequence + fallback plan if any consumer must stay on 15.

Areas to evaluate

1. Router strategy (biggest open question)

• findable-ui ships Pages Router helpers. Pages Router still works in Next 16 but is clearly deprioritized (no Cache Components support, no new caching APIs, RSC/React Compiler benefits App-Router-only).
• Audit each consumer: which are on Pages Router vs App Router vs hybrid? Decide whether findable-ui should:
  • (a) stay Pages-compatible,
  • (b) publish both Pages + App entrypoints, or
  • (c) migrate to App Router in a major version.
• next/navigation hooks already in use work in both routers — good.

2. MDX pipeline

• next-mdx-remote/serialize is used in src/utils/mdx/staticGeneration/ (Pages Router getStaticProps pattern). Confirm next-mdx-remote v5 supports Next 16.
• Evaluate whether to move to the App Router <MDXRemote /> RSC variant or @next/mdx.
• Decision affects API surface: consumers using these helpers would need to migrate if we change it.

3. Next 16 breaking changes to audit

• Node 20.9+ required (we're on 22.12 — fine; check all consumer CI/Docker).
• TypeScript 5.1+ minimum.
• Async params / searchParams / cookies() / headers() / draftMode() — only matters if we add App Router code; current library code unaffected.
• middleware.ts → proxy.ts — not used in library; check consumers.
• AMP removal — not used.
• next lint removal — migrate ESLint invocation; adopt eslint-config-next v16 flat-config default.
• next/image default changes:
  • new localPatterns requirement for local src with query strings
  • qualities default [75]
  • minimumCacheTTL 60s → 4h
  • maximumRedirects capped at 3
  • dangerouslyAllowLocalIP default off
  • Audit all <Image> usages in library and consumers.
• images.domains deprecated → remotePatterns.
• revalidateTag() signature change — not used in library; check consumers.
• Turbopack is default bundler — verify Storybook (@storybook/nextjs-vite already Vite-based — likely fine) and any consumer webpack customizations.
• React Compiler stable — opt-in; evaluate later.
• Parallel routes default.js required — consumer-side only.
• Sass modern API — check for .scss usage.
• scroll-behavior: smooth auto-apply removed — audit global styles.

4. Peer dependency coordination

• Bumping next peer to ^16 is breaking → findable-ui major version bump.
• next-auth ^4.24.13 — verify v4 works with Next 16, or plan move to next-auth v5 / Auth.js.
• @next/eslint-plugin-next, eslint-config-next — bump to 16 and migrate to flat config if not already.
• React 19.2 features (View Transitions, Activity) — opportunities, not requirements.

5. Consumer impact survey

For each consumer (data-browser, ncpi-dataset-catalog, hca-atlas-tracker, anvil-portal, brc-analytics, hprc-data-explorer, etc.): record Next version, router in use, MDX usage, middleware usage, custom webpack config, image config, and CI Node version. This determines whether we can ship the bump as a single major or need a compat window.

6. Release & rollout

• Proposed: publish findable-ui vNEXT-major with next ^16 peer; optionally keep a maintenance branch on v15 peer for one quarter if any consumer can't move immediately.
• Use npx @next/codemod@canary upgrade latest on each consumer PR.

Acceptance criteria

• Written recommendation doc in /docs or PR description
• Per-consumer ticket filed with effort estimate
• Decision on Pages vs App Router direction for the library

[frano-m]

Next.js 16 Upgrade Plan — findable-ui + Consumers

Issue: DataBiosphere/findable-ui#884
Date: 2026-04-30

---

1. Go / No-Go Recommendation

Go — with caveats. The ecosystem is well-aligned for upgrade:

• All repos already on Node 22.12.0, TypeScript ^5.9.3, React ^19 — all above Next 16 minimums.
• All consumers use output: "export" (static sites) with images: { unoptimized: true } — sidesteps most image-related breaking changes.
• No middleware, no Sass/SCSS, no AMP — several breaking changes are irrelevant.
• Pages Router still works in Next 16 — no forced migration.

Caveats / blockers to resolve first:

1. next/router usage in findable-ui — 36 files import from next/router. Pages Router APIs still work in Next 16, but they are clearly deprioritized. The library should migrate to next/navigation where possible (see Phase 1).
2. next-mdx-remote v5 compatibility — must be verified against Next 16 before proceeding.
3. next-auth v4 compatibility — only affects hca-atlas-tracker. Needs verification or upgrade to Auth.js v5.
4. ESLint flat config migration — Next 16 removes next lint; all repos use legacy .eslintrc.json.
5. next-compose-plugins compatibility — used by most consumers; may need replacement.

---

2. Current State Audit

findable-ui (library)

Aspect	Current
Peer deps	next ^15.5.13, react ^19.2.3, next-auth ^4.24.13 (optional), next-mdx-remote ^5
next/router imports	36 files (22 use useRouter)
next/navigation imports	3 files (usePathname)
next/head	2 files
next/image	Not used (custom StaticImage with <img>)
MDX	next-mdx-remote/serialize in src/utils/mdx/staticGeneration/ (Pages Router getStaticProps pattern)
Pages Router types	GetStaticPropsResult, GetStaticPathsResult, GetStaticPropsContext exported as utilities
"use client" / "use server"	None
ESLint	Legacy .eslintrc.json, eslint-config-next ^15.5.13
Storybook	@storybook/nextjs-vite ^10.3.3 (Vite-based — no webpack concern)
Node	22.12.0
TypeScript	^5.9.3

Consumer Summary

Repo	Next	Router	MDX	next-auth	Static export	Middleware	Sass	Webpack custom	ESLint
data-biosphere	^15	Pages	Yes (extensive)	No	Yes	No	No	No	Legacy JSON
anvil-portal	^15	Pages	Yes (100+ .mdx)	No	Yes	No	No	No	Legacy JSON
brc-analytics	^15	Pages	Yes (28 .mdx)	No	Yes	No	No	Sentry wrapper	Legacy JSON
data-portal	^15	Pages	Yes	No	Yes	No	No	No	Legacy JSON
hca-atlas-tracker	^15	Pages	Yes	^4	Yes	No	No	ESM transpile list	Legacy JSON
hprc-data-explorer	^15.5.13	Pages	Yes (minimal)	No	Yes	No	No	No	Legacy JSON
ncpi-dataset-catalog	^15.5.13	Pages	Yes	No	Yes	No	No	No	Legacy JSON
ucsc-brain-explorer	^15	Pages	No .mdx files	No	Yes	No	No	No	Legacy JSON

Note on app/ directories: Several repos (data-biosphere, brc-analytics, hca-atlas-tracker, hprc-data-explorer, ncpi-dataset-catalog, ucsc-brain-explorer) have an app/ directory, but it is used for application code organization (config, components, content), not as the Next.js App Router. All routing goes through pages/.

Shared baseline across all consumers:

• Node 22.12.0
• TypeScript ^5.9.3
• React ^19
• images: { unoptimized: true } — no image optimization
• output: "export" — static site generation
• No middleware, no Sass/SCSS
• Legacy .eslintrc.json
• transpilePackages: ["@databiosphere/findable-ui"]

---

3. Compatibility Matrix: Next 16 Breaking Changes

Breaking Change	findable-ui Impact	Consumer Impact	Action Required
Node 20.9+ required	None (on 22.12.0)	None (all on 22.12.0)	None
TypeScript 5.1+ required	None (on ^5.9.3)	None (all on ^5.9.3)	None
Turbopack is default bundler	Verify Storybook builds	Verify next build / next export works	Test all builds
next lint removed	Uses ESLint directly	All use eslint CLI in CI scripts	Verify CI scripts don't call next lint; migrate eslint-config-next to v16
ESLint flat config default	Legacy .eslintrc.json	All legacy .eslintrc.json	Migrate to flat config (eslint.config.mjs); update eslint-config-next to v16
Async params/searchParams	Not applicable (library)	Not applicable (static export, Pages Router)	None
middleware.ts → proxy.ts	Not used	Not used	None
AMP removal	Not used	Not used	None
next/image changes	Not used (custom StaticImage)	unoptimized: true sidesteps all changes	None
images.domains deprecated	N/A	No domains config in any consumer	None
scroll-behavior: smooth removed	Audit global styles	Audit global styles	Check if any CSS relies on this
Parallel routes default.js	N/A	No App Router usage	None
Sass modern API	No Sass	No Sass	None
revalidateTag() signature	Not used	Not used (static export)	None
React Compiler stable	Opt-in; evaluate later	Opt-in; evaluate later	Not required for upgrade

---

4. Key Decision: Router Strategy

Recommendation: (a) Stay Pages-compatible for now; incrementally migrate

Rationale:

• All 8 consumers use Pages Router exclusively for routing.
• Pages Router still works in Next 16 — it is deprioritized but not deprecated.
• Forcing an App Router migration alongside a Next 16 bump would multiply the effort and risk.
• The library's next/router usage (36 files) is substantial but mostly useRouter for basePath, pathname, query, and Router.events.

Incremental migration path:

1. Phase 1 (this upgrade): Replace next/router → next/navigation where possible (e.g., useRouter().pathname → usePathname(), useRouter().basePath stays as-is since next/navigation's useRouter doesn't expose basePath).
2. Future major: Full App Router migration as a separate initiative once consumers are ready.

next/router → next/navigation migration scope

Usage pattern	Count	Migrateable now?
useRouter().pathname	~5	Yes → usePathname()
useRouter().asPath	~5	Yes → usePathname() + useSearchParams()
useRouter().push() / .replace()	~8	Yes → useRouter() from next/navigation
useRouter().basePath	~4	No — next/navigation doesn't expose basePath
useRouter().query	~5	Partial → useSearchParams() for query strings; dynamic route params need different approach
Router.events (routeChangeStart etc.)	1 file	No — no equivalent in next/navigation; keep next/router import
GetStaticPropsResult / GetStaticPathsResult types	3 files	No — these are Pages Router SSG types, still valid

Conclusion: ~18 of 36 files can migrate to next/navigation. The remaining ~18 must keep next/router for basePath, Router.events, and SSG types. This is acceptable since Pages Router APIs remain available in Next 16.

---

5. MDX Pipeline

Current: next-mdx-remote v5 with serialize() called in getStaticProps pattern.

Action items:

1. Verify next-mdx-remote v5 works with Next 16 (check their release notes / issues).
2. If v5 is incompatible, evaluate next-mdx-remote v6+ or @next/mdx as replacement.
3. The staticGeneration/ utilities in findable-ui export getStaticProps/getStaticPaths helpers — these remain valid under Pages Router in Next 16.

Risk: Low — next-mdx-remote is widely used and likely to support Next 16 promptly.

---

6. next-auth (hca-atlas-tracker only)

Current: next-auth ^4.24.13 as optional peer dep in findable-ui; used only by hca-atlas-tracker.

Action items:

1. Verify next-auth v4 works with Next 16 (check compatibility matrix).
2. If v4 is incompatible, plan migration to Auth.js v5 (next-auth@5 / @auth/nextjs).
3. findable-ui's next-auth integration is thin (SessionProvider wrapper, signIn/signOut calls) — migration surface is small.

Risk: Medium — next-auth v4 may lag behind Next 16 support. Auth.js v5 migration is a separate effort but scoped.

---

7. ESLint Migration

All repos use legacy .eslintrc.json with eslint-config-next. Next 16 removes next lint and defaults to flat config.

Action items:

1. Upgrade eslint-config-next and @next/eslint-plugin-next to v16 in all repos.
2. Migrate from .eslintrc.json to eslint.config.mjs (flat config).
3. Update CI scripts if any call next lint — replace with npx eslint . or equivalent.
4. Verify all plugins support flat config: @typescript-eslint, sonarjs, prettier, jsdoc, sort-destructure-keys, typescript-sort-keys, eslint-comments.

Risk: Medium — flat config migration touches every repo and every plugin. Can be done as a separate preparatory PR before the Next 16 bump.

---

8. next-compose-plugins Compatibility

Most consumers use next-compose-plugins to compose @next/mdx with other config.

Action items:

1. Verify next-compose-plugins works with Next 16's config format.
2. If incompatible, replace with native Next.js config composition (Next 16 supports function composition natively).

Risk: Low — replacement is straightforward.

---

9. Effort Estimates Per Consumer

Repo	Effort	Notes
findable-ui	M	Bump peer deps, partial next/router → next/navigation migration, ESLint flat config, verify Storybook
data-biosphere	S	Bump next, ESLint flat config, verify build + tests
anvil-portal	S	Bump next, ESLint flat config, verify build + tests
brc-analytics	S	Bump next, ESLint flat config, verify Sentry config, verify build + tests
data-portal	S	Bump next, ESLint flat config, verify build + tests
hca-atlas-tracker	M	Bump next, ESLint flat config, next-auth compatibility, verify build + tests
hprc-data-explorer	S	Bump next, ESLint flat config, verify build + tests
ncpi-dataset-catalog	S	Bump next, ESLint flat config, verify build + tests
ucsc-brain-explorer	S	Bump next, ESLint flat config, verify build + tests

---

10. Proposed Phased Rollout

Phase 0: Pre-upgrade preparation (can start now)

1. ESLint flat config migration — do this across all repos as a standalone PR series (not blocked by Next 16).
2. Verify third-party compatibility:
   • next-mdx-remote v5 + Next 16
   • next-auth v4 + Next 16
   • next-compose-plugins + Next 16
   • @storybook/nextjs-vite + Next 16
3. Audit CI scripts for any next lint invocations.

Phase 1: findable-ui library upgrade

1. Bump next peer dep from ^15.5.13 to ^15.5.13 || ^16.
   • Using an OR range allows consumers to upgrade at their own pace.
   • This avoids a hard major version bump initially.
2. Migrate next/router → next/navigation where possible (~18 files).
3. Bump eslint-config-next and @next/eslint-plugin-next to v16.
4. Verify Storybook builds with Next 16.
5. Run full test suite.
6. Publish as a new minor/major version (major if any export signatures change due to router migration).

Phase 2: Consumer upgrades (can be parallelized)

For each consumer, in a single PR:

1. Run npx @next/codemod@canary upgrade latest to auto-fix known patterns.
2. Bump next to ^16.
3. Bump @databiosphere/findable-ui to the Phase 1 release.
4. Bump eslint-config-next / @next/eslint-plugin-next to v16.
5. Update next-compose-plugins usage if needed.
6. Verify next build succeeds.
7. Run unit tests + Playwright e2e tests.
8. Deploy to staging and smoke test.

Suggested consumer order:

1. ucsc-brain-explorer — smallest, no MDX, no next-auth (canary)
2. hprc-data-explorer — small, minimal MDX
3. ncpi-dataset-catalog — small-medium
4. data-portal — medium
5. data-biosphere — medium, extensive MDX
6. brc-analytics — medium, Sentry integration
7. anvil-portal — large, 100+ MDX files
8. hca-atlas-tracker — medium, next-auth dependency (do last to allow most time for auth compatibility)

Phase 3: Cleanup (optional, after all consumers upgraded)

1. Narrow findable-ui peer dep from ^15.5.13 || ^16 to ^16 only.
2. This becomes a new major version of findable-ui.
3. Remove any Next 15 compatibility shims.
4. Drop the maintenance branch if one was created.

---

11. Fallback Plan

If any consumer cannot upgrade to Next 16 within the compatibility window:

1. Keep the ^15.5.13 || ^16 peer dep range in findable-ui indefinitely.
2. Create a next-15 maintenance branch in findable-ui for critical fixes only.
3. The stuck consumer stays on the last findable-ui version before Phase 3.
4. Set a sunset date (e.g., 1 quarter) after which the maintenance branch is archived.

---

12. Open Questions

1. Should the next/router → next/navigation migration in findable-ui be done as part of this upgrade or as a separate preceding PR?
2. Is there appetite for a full App Router migration in a future cycle, or should the library remain Pages Router-compatible indefinitely?
3. Should ESLint flat config migration be done repo-by-repo or in a coordinated batch?
4. Does hca-atlas-tracker have plans to move from next-auth v4 to Auth.js v5 independently?