React upgrades 17 -> 19

[dex4er]

Currently we use React 17 in the project that was developed actively in 2020-2021.

The goal is to upgrade React to 19 if possible or at least to 18 if we would need intermediate upgrade first.

[dex4er]

@claude [model:fable] Analyze our situation and propose the plan.

[claude]

Claude finished @dex4er's task in 5m 37s —— View job

---

React Upgrade Analysis and Plan

• Survey React and React-ecosystem dependencies across the monorepo
• Identify React 17-era APIs in use
• Check blockers: mobx-react, react-router, react-select, testing libraries
• Assess extension compatibility implications
• Write the upgrade plan

Current state

React ^17.0.2 and @types/react 17 are declared in 17 workspace packages (each with its own version string — there is no pnpm catalog, so keeping them in lockstep is manual today). Key ecosystem versions:

Dependency	Version	React 18	React 19
react / react-dom	17.0.2	upgrade target	final target
mobx-react	7.6.0 (8 pkgs)	needs 9.x	9.2+ OK
react-router(-dom)	5.3.4 + history 4.10	works (peer >=15), unmaintained	blocker — needs v6/v7 migration
mobx-observable-history	2.0.3	tied to history v4, abandoned upstream	blocker — must be replaced
react-beautiful-dnd	13.1.1	archived, StrictMode-broken	blocker — replace with @hello-pangea/dnd
@testing-library/react	12.1.5 (8 pkgs)	needs 13+	needs 16.x
react-select	5.10.2	OK	OK
react-table	7.8.0	OK	works, unmaintained (consider @tanstack/react-table later)
react-window	1.8.11	OK	peer range ends at 18 — needs v2 or peer override

Codebase facts that shape the plan:

• Legacy render entry is tiny and centralized: ReactDOM.render lives in one place (packages/technical-features/react-application/src/render-application/render.injectable.tsx:16) and unmountComponentAtNode in one (packages/core/src/renderer/before-frame-starts/runnables/listen-unload.injectable.ts:38). The createRoot migration is a small, contained change (the root instance must be shared between those two injectables).
• Classic JSX transform: root tsconfig.json:3 has "jsx": "react". Moving to "react-jsx" is a prerequisite for 19 and can be done today on 17 with zero runtime change.
• 174 files with class components — still fully supported in 18 and 19, no forced rewrite.
• No hard-removed APIs in use: no string refs, no legacy context, no findDOMNode, no propTypes. defaultProps appears in 24 files — fine on class components, but any on function components must move to default parameters before 19.
• No StrictMode anywhere — one less source of double-render surprises during the bump.
• react-router usage is contained (~40 files) because Freelens routes mostly through its own injectable route registry and navigateTo abstractions; the direct RR surface is Route/Router plumbing plus mobx-observable-history.
• Extensions: in v2, extensions consume the API via the FreelensExtensionApi runtime global and are loaded with a plain require (extension-loader.ts:408). React is not re-exported through the API, so whatever React copy an extension bundles must match the host's major (hooks break across React instances rendered in one tree). A React major bump is therefore an extension-facing breaking change — which is exactly why it should ride the already-breaking v2 wave rather than land separately.
• Electron 41 imposes no constraint; Chromium is modern enough for 19.

Recommendation

Go to React 18.3 first, then 19, as separate releases. React 18.3.1 exists specifically as the stepping stone: it runs everything 17 runs and warns about everything 19 removes. Jumping straight to 19 would force the react-router 5 replacement, the testing-library jump, mobx-react jump, and the new-root migration into one giant, hard-to-bisect change.

Phase 0 — Preparation (on React 17, independently mergeable PRs)

1. Switch the JSX transform to "jsx": "react-jsx" (tsconfig + biome/vite config), codemod away now-unused import React defaults.
2. Replace react-beautiful-dnd with @hello-pangea/dnd — used in exactly one component (packages/core/src/renderer/components/hotbar/hotbar-menu.tsx) plus its mock, so this is a small PR.
3. Audit the 24 defaultProps files; convert function-component usages to default parameters (class components can stay).
4. Optionally introduce a pnpm catalog for react/react-dom/@types/react* so 17 packages bump atomically in later phases.

Phase 1 — React 18.3

1. Bump react/react-dom to 18.3.1 and @types/react* to 18 across all packages.
2. Migrate render.injectable.tsx to createRoot and listen-unload to root.unmount().
3. mobx-react 7 → 9 (class observer still supported; mobx 6.15 already satisfies it) and align mobx-react-lite.
4. @testing-library/react 12 → 15, user-event stays 14. Expect churn: async act semantics and automatic batching change timing-sensitive tests; regenerate snapshots per AGENTS.md.
5. Keep react-router 5 (peer-compatible) — explicitly not part of this phase.
6. Do not enable StrictMode yet; fix the 18.3 deprecation warnings it surfaces in the console instead — they are the exact 19 checklist.
7. Verify extension loading against the example extension and document the required React version for extension authors.

Phase 2 — Routing modernization (the real React 19 gate)

react-router 5 + history 4 + mobx-observable-history is the one subsystem that cannot come along to 19. Two options:

• (a) Migrate to react-router 6/7 (Switch → Routes, useHistory → useNavigate, Redirect → Navigate) and replace mobx-observable-history with a thin in-house mobx wrapper over the router's navigator/location. ~40 files.
• (b) Drop react-router entirely in favor of the existing internal route registry, which already owns route definitions and navigation. Larger change, but removes two unmaintained dependencies permanently.

I recommend scoping (b) first — if the internal router already covers matching/rendering, RR5 may be nearly vestigial; otherwise fall back to (a). Either way this phase is independent of the React version and can proceed on 18.

Phase 3 — React 19

1. Bump react/react-dom/types to 19, @testing-library/react to 16.
2. react-window → v2 (or peer override), re-evaluate react-table 7 (works, but @tanstack/react-table is the maintained successor — separate effort).
3. Optional cleanups: forwardRef (6 usages) → ref-as-prop, Context.Provider → <Context>.
4. Announce the extension-facing break: extensions must build against React 19 types (bundle with @freelensapp/extensions next major).

Risk notes

• Highest-risk item overall is the testing-library + act semantics churn in Phase 1 (8 packages of tests) and the routing migration in Phase 2 — everything else is mechanical.
• Automatic batching in 18 can change behavior of code that relies on synchronous re-render after state changes outside React events; mobx-driven rendering is mostly insulated, but the terminal/dock and drag-drop areas deserve manual smoke testing (/run-style verification per release).
• The extension React-sourcing question (bundled vs. host-provided) should be settled explicitly during Phase 1 — today nothing in the loader pins it, and a version mismatch fails only at runtime with "invalid hook call".

If this plan looks right, a sensible first concrete step is Phase 0 items 1–2 as two small PRs; say the word and I can start on those.
| Model: claude-fable-5

[dex4er]

@claude Create an issue for phase 0 to track separate changes

[claude]

Claude finished @dex4er's task in 38s —— View job

---

Create Phase 0 tracking issue

• Draft the Phase 0 issue (preparation tasks on React 17)
• Create the issue via gh
• Link it back here

Created #2251 — React upgrade — Phase 0: preparation on React 17.

It tracks the four Phase 0 items from the plan, each intended as its own PR:

1. Switch the JSX transform to "jsx": "react-jsx" and codemod away unused default import React statements.
2. Replace react-beautiful-dnd with @hello-pangea/dnd (one component + mock).
3. Audit the 24 defaultProps files; convert function-component usages to default parameters.
4. (Optional) Introduce a pnpm catalog for react / react-dom / @types/react*.

The issue references this one (#2154) as the parent plan.
| Model: claude-opus-4-8

[dex4er]

@claude Create the issue for tasks in Phase 1

[claude]

Claude finished @dex4er's task in 52s —— View job

---

Create Phase 1 tracking issue

• Review the Phase 1 plan and React upgrade — Phase 0: preparation on React 17 #2251 (Phase 0) for formatting
• Draft the Phase 1 issue (React 18.3 upgrade)
• Create the issue via gh
• Link it back here

Created #2253 — React upgrade — Phase 1: React 18.3.

It tracks the seven Phase 1 items from the plan, each intended as its own PR where practical:

1. Bump react / react-dom to 18.3.1 and @types/react* to 18 across all packages (via the pnpm catalog from Introduce pnpm catalog for React 17 dependencies #2252).
2. Migrate to the new root API — render.injectable.tsx → createRoot, listen-unload → root.unmount() (shared root instance).
3. Upgrade mobx-react 7 → 9 and align mobx-react-lite.
4. Upgrade @testing-library/react 12 → 15 (user-event stays 14).
5. Fix 18.3 deprecation warnings; do not enable StrictMode yet.
6. Verify extension loading against the example extension and document the required React version.

Routing modernization (react-router 5, mobx-observable-history), React 19, and StrictMode are explicitly called out as out of scope, to be handled in Phases 2 and 3. The issue references this one (#2154) as the parent plan.

[dex4er]

@claude Create issue for phase 2

[claude]

Claude finished @dex4er's task in 52s —— View job

---

Create Phase 2 tracking issue

• Review the Phase 2 plan and React upgrade — Phase 0: preparation on React 17 #2251 / React upgrade — Phase 1: React 18.3 #2253 for formatting
• Draft the Phase 2 issue (routing modernization)
• Create the issue via gh
• Link it back here

Created #2261 — React upgrade — Phase 2: routing modernization.

It tracks the Phase 2 work — replacing the one subsystem that cannot come along to React 19: react-router 5 + history 4 + mobx-observable-history. Key points captured:

• Two approaches, with a recommendation to scope (b) drop react-router in favor of the internal route registry first, falling back to (a) migrate to react-router 6/7 if the internal registry does not fully cover matching/rendering.
• Replace mobx-observable-history (abandoned, tied to history v4) with a thin in-house mobx wrapper — required regardless of approach.
• Remove history v4 once nothing depends on it.
• Smoke-test navigation flows and the extension-facing routing API.

The issue notes routing is independent of the React version (can proceed on React 18) and is the real gate for Phase 3 (React 19). React 19, StrictMode, react-window v2, and @testing-library/react 16 are explicitly out of scope. It references #2154 as the parent plan.