dirtydishes/islandflow
1
0
Fork 0
Code Issues 2 Pull requests 4 Projects Releases Packages Wiki Activity Actions 1

Gate live feed staleness and isolate Next dev artifacts

Browse source 
- delay stale status for paused live feeds before surfacing disconnects
- keep `next dev` output separate from production build artifacts
- add coverage for the new live-feed stale threshold
This commit is contained in:
dirtydishes 2026-05-06 22:14:11 -04:00 • committed by dirtydishes
parent 4368d6db4c
commit 1161e37ef5
8 changed files with 130 additions and 6 deletions
Download patch file Download diff file Expand all files Collapse all files

79
plans/nextjs-upgrade-plan.md Normal file
View file

@ -0,0 +1,79 @@
# Next.js Upgrade Plan: `14.2.35` -> `16.2.4` (via v15 compatibility pass)
## Summary
As of **May 5, 2026**, the web app is on Next `14.2.35` (locked) with React `18.3.1`, while npm `latest` for `next` is `16.2.4`.
Based on repo inspection, risk is **moderate-low** for this app because it uses App Router with minimal server-only APIs and no custom webpack/middleware. The main required migration is the React 19 + Next 15/16 compatibility surface.
## Current-State Findings
- Declared deps: [apps/web/package.json](/Users/kell/Cloud/dev/islandflow/apps/web/package.json:13)
- Locked Next version: [bun.lock](/Users/kell/Cloud/dev/islandflow/bun.lock:241)
- Next config is simple (`distDir` only), no webpack/turbopack overrides: [apps/web/next.config.mjs](/Users/kell/Cloud/dev/islandflow/apps/web/next.config.mjs:1)
- App Router only (`app/*`), no route handlers or middleware in `apps/web`
- No `cookies()`, `headers()`, `draftMode()`, or `params/searchParams` async-migration hotspots found in `apps/web/app`
- Baseline build passes on current branch (`bun --cwd=apps/web run build`)
## Public APIs / Interfaces / Types Impact
- External API contracts for the project: **no intentional changes**
- Dependency interface upgrades required:
- `next` -> `16.2.4`
- `react` / `react-dom` -> `19.x`
- `@types/react` / `@types/react-dom` -> latest 19-compatible
- If future server components introduce request APIs, they must follow async forms from v15+ (`await cookies()`, etc.)
## Implementation Plan
1. Create an upgrade branch and snapshot baseline:
- Record current `bun --cwd=apps/web run build` and `bun test` status.
2. Upgrade deps in `apps/web`:
- Bump `next`, `react`, `react-dom`, and React type packages to latest compatible.
- Run install and refresh lockfile.
3. Run codemod-assisted checks:
- Use Next codemod guidance for v15/v16 migration candidates.
- Verify no required transforms are missed, especially async request APIs and config migrations.
4. Validate Next 16 runtime/build behavior:
- `bun --cwd=apps/web run build`
- `bun --cwd=apps/web run dev` smoke test for `/`, `/tape`, and redirect routes.
5. Validate tests:
- `bun test apps/web/app/routes.test.ts`
- `bun test apps/web/app/terminal.test.ts`
- `bun test` repo-wide if CI parity is expected.
6. Fix issues discovered in validation:
- Resolve React 19 typing/hook warnings if any appear.
- Confirm no changed behavior in navigation/replay/tape flows.
7. Final verification:
- Re-run build and relevant tests.
- Capture upgrade notes, what changed, what was checked, and residual risk.
## Test Cases and Scenarios
- Build:
- Production build succeeds (`next build`) with Next 16 + React 19.
- Routing:
- `/` and `/tape` render correctly.
- `/signals`, `/charts`, `/replay` still redirect to `/`.
- Client navigation/cache behavior:
- `<Link>` navigation between Home/Tape remains correct under updated client cache semantics.
- Live/replay terminal UI:
- No regressions in fetch-driven panels and websocket-driven status behavior.
- Type safety:
- No TypeScript errors from React 19 types in terminal-heavy UI code.
- Regression check:
- Existing Bun tests continue to pass.
## Assumptions and Defaults Chosen
- Target selected: **Next 16 latest**
- Default strategy: **single upgrade stream with v15 compatibility checks included**, not a prolonged 14 -> 15 -> 16 rollout, because the code has low exposure to v15 breaking server APIs
- No custom webpack migration required unless hidden plugin behavior introduces it
- No expected changes to backend service contracts or shared `@islandflow/types` interfaces
## Official References
- Next 15 upgrade guide: https://nextjs.org/docs/app/guides/upgrading/version-15
- Next 16 upgrade guide: https://nextjs.org/docs/app/guides/upgrading/version-16
- Next 15 release notes: https://nextjs.org/blog/next-15
- npm package page: https://www.npmjs.com/package/next