TypeScript and React

Budget: 2-3 weeks.

Why this matters

The frontend is the weakest layer in the current codebase. It is plain JSX with no types. You have already said design quality matters. Adding types catches most of the bugs you will hit as you add features, and it gives future hires a codebase they can navigate without reading every function.

What to learn

Topic	Time
Modern JavaScript: arrow functions, destructuring, spread, async/await, modules, array methods	1-2 days
TypeScript handbook (first half): interfaces, types, generics, unions, narrowing	2-3 days
React mental model: UI as a function of state, pure components, effects as sync boundaries	2 days
Hooks you will actually use: `useState`, `useEffect`, `useMemo`, `useCallback`, `useRef`	2 days
One throwaway React app (todo list or weather fetcher) to get reps	1 day
`openapi-typescript` setup against the FastAPI `/openapi.json`	0.5 day
Port leaf components in `frontend/src/components/` from `.jsx` to `.tsx`	3-4 days
Port `App.jsx` to `App.tsx` once the types are in place	2 days

Resources

react.dev/learn: official React tutorial, the one to read cover to cover.
TypeScript handbook: start with "The Basics," "Everyday Types," and "Narrowing."
"A Complete Guide to useEffect" by Dan Abramov: the single best explanation of effects.
"Before You memo()" by Dan Abramov: when not to reach for useMemo / useCallback.
openapi-typescript: generates TS types from the FastAPI /openapi.json.

Exercise

Port frontend/src/App.jsx and the components in frontend/src/components/ to TypeScript. Start with leaf components (MapSettingsPanel, RouteDetail, KpiPanel) and work up to App.tsx. Run openapi-typescript against the FastAPI server's /openapi.json and import the generated types into useChat.ts so the SSE payloads are typed. When you are done, remove allowJs from tsconfig.json and make sure the build is clean.

Notes

Read React quickstart and tutorial. I mostly learned to think more about state and setState, and props (which are data passed from parent to child component but not really state).
Went through https://www.typescriptlang.org/docs/handbook/2/basic-types.html. TypeScript is a superset of JavaScript designed in 2012 to catch type errors. Most notably, JavaScript has weird undefined behaviour when accessing properties that don't exist, which TypeScript will just catch. Type hinting works just like Python, but JavaScript is a nasty language with edge cases that I have yet to learn more about.
Went through https://www.typescriptlang.org/docs/handbook/2/everyday-types.html. Primitives are string, number (no float/int separation), and boolean. Type-hinting really looks like Python style. What's different is object types, which are typed like function printCoord(pt: { x: number; y: number }) to say that pt has x and y properties. Optional properties look like function printName(obj: { first: string; last?: string }) where last may be optional. This object notation is new to me, but fortunately there is type alias:
```
type Point = {
  x: number;
  y: number;
};
```
or through interfaces:
```
interface Point {
  x: number;
  y: number;
}
```
The difference between type and interface is that interface can be easily extended with new fields (but I don't know why you would do this). Always use strictNullChecks to get rid of the weird null/undefined JavaScript behavior.
JavaScript primers to read before going deeper into TypeScript:
- https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/A_re-introduction_to_JavaScript - the classic single-page primer. Covers types, operators, control flow, objects, arrays, functions, closures. Designed exactly for "I know how to program, just teach me JS." Start here.
- https://observablehq.com/@ballingt/javascript-for-python-programmers - very short Observable notebook, contrasts JS to Python directly. Good as a follow-up after MDN to nail the differences (truthiness, == vs ===, var/let/const, prototypes).