1.1 Why not just plain JavaScript and the DOM?🔗

You could write document.createElement, wire up addEventListener, and manually update the page every time a task changes. People did this for a decade, and it produced a specific kind of bug: the screen and the data disagreeing. You delete a task from the array but forget to remove its <li>; now the UI is lying. The core problem is manual synchronization — every piece of state has to be hand-copied into the DOM, and every copy is a chance to get it wrong.

React’s one big idea kills that class of bug:

The UI is a function of state. You describe what the screen should look like for a given state, and React figures out the DOM operations to make it so. You never touch the DOM; you change state and re-describe.

Intuition — the thermostat vs. the furnace. Old-style DOM code is a furnace: you manually turn heat up and down and hope the room lands at the right temperature. React is a thermostat: you declare “I want 70°” and the system drives the actuators. You stopped managing steps; you started declaring outcomes.

1.2 Why TypeScript?🔗

Your backend already validates data — Pydantic rejects a task with no title. But the browser is a different program, in a different language, that only learns the shape of a Task at runtime, by receiving JSON. Nothing stops you from writing task.titel (typo) or treating due as a Date when the server sends a string. In plain JavaScript, that’s a blank screen and a console error a user hits in production.

TypeScript moves that error to compile time. You write down the shape of a Task once, as an interface, and every misuse — the typo, the wrong type, the field you forgot the server can send null for — becomes a red squiggle in your editor and a failed CI check. This is the same shift the eval lecture made (catch regressions before shipping) and the testing lecture made (catch bugs before users), applied to the frontend/backend seam, which is exactly where full-stack bugs concentrate.

1.3 Where this sits in the stack🔗

The dashed line is the theme of the whole lecture: types.ts on the browser side is a mirror of models.py on the server side. Keeping that mirror honest — by hand today, with codegen in industry — is what “full-stack integration” actually means.

Step 1. Check that Node.js is installed🔗

In your terminal:

node --version
npm --version

If both commands print a version, you are ready. If not, install Node.js (the LTS release) first.

Step 2. Create the project🔗

npm create vite@latest hello-react -- --template react-ts
cd hello-react
npm install

The react-ts template is the React + TypeScript scaffold; npm install downloads the dependencies into node_modules/.

Step 3. Replace App.tsx🔗

Open the app’s single component:

Replace its contents with:

function App() {
  return <h1>Hello, World!</h1>;
}

export default App;

That is a complete React component: a function that returns a description of UI. We unpack exactly what that means in §3.

Step 4. Start the dev server🔗

npm run dev

You will see something similar to:

Local:   http://localhost:5173/

Open that address in your browser. You should see Hello, World!

Step 5. Watch hot reloading, and add state🔗

When you save a change to App.tsx, Vite notices and updates the browser automatically — no manual refresh. Leave the server running and replace App.tsx with a counter:

import { useState } from 'react';

function App() {
  const [count, setCount] = useState(0);

  return (
    <>
      <h1>Count: {count}</h1>
      <button onClick={() => setCount(count + 1)}>
        Increment
      </button>
    </>
  );
}

export default App;

Click the button and watch the heading change. You never wrote code to update that <h1>: you changed state, and React re-rendered the UI to match. That is the whole model — UI is a function of state — and §4 makes useState precise.

Note. The useState import from react at the top is required; forgetting it is the first error most students hit. The <>...</> is a fragment, which lets a component return two sibling elements without wrapping them in an extra <div> (see §3.1).

3.1 Components🔗

A React component is a JavaScript/TypeScript function that takes a single props object and returns a description of UI (a React element tree, written in JSX). React calls your function and reconciles its output with the real DOM.

Plain English. A component is a reusable custom HTML tag you define with a function. <TaskItem task={...} /> looks like an element but is really a function call.

JSX is the HTML-looking syntax inside the function. It is not HTML and not a string — it’s syntax sugar that compiles to function calls. A few rules bite everyone once:

• Return one root element (wrap siblings in a parent or a <>…</> fragment).

• class becomes className (because class is a reserved word in JS).

• { } drops you back into JavaScript: {task.title}, {done ? "✓" : ""}.

Common misconception: “JSX is a template string.” No — {task.title} is a real expression evaluated by JS, type-checked by TypeScript, with full editor autocomplete. A template string is opaque text; JSX is code.

The smallest possible component. Before the real thing, here is a component with no props at all — it is just a function that returns JSX:

function Greeting() {
  return <h1>Hello!</h1>;
}

Components compose: you use one inside another exactly as you’d use a built-in tag, and that is how a page gets built out of parts.

function App() {
  return (
    <>
      <Greeting />
      <TaskList />
    </>
  );
}

That <>…</> is the fragment from the rules above: App returns one root, and the fragment groups two siblings without adding a pointless <div> to the DOM.

Worked example. Now the real one — our smallest useful component, one task row:

export function TaskItem({ task, onToggle, onDelete }: TaskItemProps) {
  return (
    <li className={`task priority-${task.priority}`}>
      <label>
        <input type="checkbox" checked={task.done} onChange={() => onToggle(task)} />
        <span className={task.done ? "done" : ""}>
          <strong>{task.title}</strong> — {task.course}
        </span>
      </label>
      <button type="button" onClick={() => onDelete(task.id)}>✕</button>
    </li>
  );
}

Read it as: “given a task and two callbacks, here is the <li> that represents it.” Notice there is no DOM manipulation — no appendChild, no .innerHTML. You describe; React renders.

3.2 Props🔗

Props (properties) are the single input argument to a component: a read-only object passed by the parent. Data flows down, from parent to child.

Plain English. Props are function arguments for components. <TaskItem task={t} /> passes t as props.task.

Intuition. Props are the “wiring diagram” of your UI. The parent decides what data and which callbacks each child gets; the child can’t reach up and grab anything else. This one-way flow is why React apps stay debuggable at scale: to understand a component, you only read its props, not the whole program.

Common misconception: “A child can change its props.” Props are read-only. A child that wants to change something calls a callback the parent passed down (that’s what onToggle/onDelete are). The parent owns the data; the child requests changes. This “data down, events up” pattern is the backbone of React.

Practical implication. Components split cleanly into two kinds: presentational (just render props — TaskItem, NewTaskForm) and container (own state and logic — App, and the useTasks hook). Keeping rows dumb makes them trivial to test and reuse.

4.1 The hook🔗

useState<T>(initial) returns a tuple [value, setValue]. value is the current state for this render; setValue(next) asks React to re-render this component with new state.

Plain English. useState gives a component a memory cell that survives re-renders, plus a setter. Calling the setter re-runs the component function with the new value.

const [title, setTitle] = useState("");        // T inferred as string
const [priority, setPriority] = useState<Priority>("medium");  // T given explicitly

Aside: that <T> is a generic type. This is the first place the lecture needs one, so let’s name it. A generic is a type with a hole in it, filled in at the point of use — useState isn’t “state of one particular type,” it’s “state of whatever type you hand it.” Writing useState<Priority>("medium") says this cell will always hold a Priority, and the compiler then knows that priority is a Priority and that setPriority("urgent") is an error. You will see the same angle-bracket notation on useState<Task[]>([]) in §9 (“an array of Task”) and on our own handle<T> helper in §7.3.

When can you leave it off? When TypeScript can infer it from the initial value: useState("") obviously holds a string. You supply it explicitly when the initial value is less informative than the truth — useState([]) would infer never[], which is why the task list needs useState<Task[]>([]) to be usable.

Intuition — the render loop. A component function runs, returns JSX, React paints. When you call setTitle("Read"), React schedules another run of the same function; this time useState hands back "Read", the JSX differs, React updates only what changed. State is the input to each render; the setter is how you request the next render.

Common misconception #1: “setState updates the variable immediately.” It does not. title is a const for the duration of this render. setTitle("x") schedules a future render where title will be "x". Reading title on the very next line still gives the old value. State updates are requests, not assignments.

Common misconception #2: “I can just push to the array in state.” Never mutate state in place:

tasks.push(newTask);          // WRONG: React sees the same array reference, skips re-render
setTasks([...tasks, newTask]); // new array → React re-renders

React decides whether to re-render by comparing references. Mutating keeps the same reference, so your change is invisible. Always produce a new array/object.

Worked example — a controlled input. In NewTaskForm, the text box’s value is React state:

<input value={title} onChange={(e) => setTitle(e.target.value)} />

Every keystroke fires onChange → setTitle → re-render → the input shows the new title. React state is the single source of truth; the DOM input just reflects it. This is a controlled component, and it’s why clearing the form after submit is just setTitle("").

6.1 Interfaces that mirror the backend🔗

An interface (or type) describes the shape of an object: which fields exist and what type each is. TypeScript checks every use against it and erases it at build time (types don’t exist at runtime).

The single most important file in the app is src/types.ts, and it is a hand-mirror of the server’s app/models.py:

// Mirrors the server's Priority string enum.
export type Priority = "low" | "medium" | "high";

// Mirrors the `Task` Pydantic model (what the server returns).
export interface Task {
  id: number;
  title: string;
  course: string;
  due: string | null;   // JSON has no date type: a `date` arrives as an ISO string
  priority: Priority;
  done: boolean;
}

// Mirrors `TaskCreate` (what we POST). No id/done — the server owns those.
export interface TaskCreate {
  title: string;
  course: string;
  due?: string | null;
  priority: Priority;
}

Line up models.py and types.ts side by side and you can see the contract. Three translations are worth calling out, because they’re where full-stack bugs live:

• date → string | null. JSON has no date type. FastAPI serializes a Python date to "2026-03-01". If you typed due: Date, you’d be lying — new Date(task.due) would be your job, and TypeScript would (correctly) let you forget it.

• Pydantic Priority enum → a TS union of string literals. "low" | "medium" | "high" means the compiler rejects priority: "urgent" before it ever reaches the server’s validator.

• Optional vs. nullable. due?: string | null says two different things at once: the field may be absent from the object we send (?), and its value may be null. Both are true for TaskCreate.due.

Common misconception: “TypeScript validates the API response at runtime.” It does not. Types are erased before the code runs. const t = await res.json() as Task is a promise you make to the compiler, not a check. If the server actually sends { titel: ... }, TypeScript is none the wiser at runtime — it trusts your cast. (Runtime validation needs a library like Zod; that’s the intermediate exercise.) What types buy you is that everywhere else in your code, using t.title is checked, and t.titel is a compile error.

6.2 Typed props and state🔗

Props get an interface; state gets a type argument when inference isn’t enough:

interface TaskItemProps {
  task: Task;
  onToggle: (task: Task) => void;   // a callback: takes a Task, returns nothing
  onDelete: (id: number) => void;
}

export function TaskItem({ task, onToggle, onDelete }: TaskItemProps) { … }

Now the compiler enforces the wiring diagram: render <TaskItem /> without an onDelete, or pass onDelete={() => …} that expects a string, and it’s a red error at the call site, in the parent, before you ever run the app. The bug can’t reach the browser.

Worked example — the error TypeScript catches for free. Suppose the backend team renames done to completed in models.py. You update types.ts to match. Instantly, tsc flags every place that read task.done — TaskItem’s checkbox, useTasks’ toggle, the .done CSS class. You get a to-do list of exactly what to fix, generated by the compiler. In plain JS, you’d find those one blank checkbox at a time, in production.

7.0 The other side of the wire🔗

Before writing a line of browser code, put the server back on screen. This is the TerpTasks route from the FastAPI lecture — the thing our fetch is about to call:

# app/main.py (server side)
@app.get("/tasks", response_model=list[Task])
def list_tasks(course: str | None = None):
    return store.list(course=course)

and this is what it puts on the wire:

[
  {"id": 1, "title": "Finish FastAPI reading", "course": "CMSC389A",
   "due": "2026-03-01", "priority": "high", "done": false}
]

Keep both in view for the rest of the section. Everything that follows — the fetch call, the Task interface, the handle<T> helper — exists to move that JSON across the language boundary without either side lying about its shape.

7.1 async/await and Promises🔗

Network calls take time, so they’re asynchronous: the function returns a Promise immediately and the result arrives later. async/await lets you write that in a straight line:

async function load() {
  const res = await fetch(url);   // pause here until the response arrives
  const data = await res.json();  // pause again while the body is parsed
  return data;                    // the Promise this function returns resolves to `data`
}

await doesn’t block the browser — it yields, lets the UI stay responsive, and resumes when the Promise settles. Anything that can await can also throw, so async functions pair with try/catch.

7.2 fetch vs. Axios🔗

Two common ways to make the call. Here is the same create request both ways:

// fetch — built into the browser, zero dependencies
const res = await fetch(`${BASE}/tasks`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(data),
});
if (!res.ok) throw new ApiError(res.status, "…");  // you MUST check ok yourself
const task: Task = await res.json();               // and parse the body yourself

// axios — a small library
const { data: task } = await axios.post<Task>(`${BASE}/tasks`, data);
// auto-JSON in and out; throws on 4xx/5xx automatically

The one fetch gotcha that bites everyone: fetch only rejects on a network failure (server unreachable). A 404 or 500 is a successful fetch of an error response — res.ok is false, but the Promise resolves. If you forget to check res.ok, you’ll happily res.json() an error body and treat it as data. Axios rejects on 4xx/5xx, which is why many teams prefer it. Our project uses fetch and centralizes the res.ok check in one place so no call site can forget — which is the next point.

7.3 One typed client module🔗

Components should never call fetch directly. All network code lives in src/api.ts, exactly like the backend keeps storage in one layer. Here is the heart of it:

const BASE_URL: string = import.meta.env.VITE_API_URL ?? "http://127.0.0.1:8000";

export class ApiError extends Error {
  constructor(public readonly status: number, message: string) {
    super(message);
    this.name = "ApiError";
  }
}

// Turn a Response into typed data, or throw. The `ok` check lives HERE, once.
async function handle<T>(res: Response): Promise<T> {
  if (!res.ok) {
    let detail = res.statusText;
    try {
      const body = (await res.json()) as { detail?: string };  // FastAPI: {"detail": "..."}
      if (body.detail) detail = body.detail;
    } catch { /* non-JSON error body */ }
    throw new ApiError(res.status, detail);
  }
  if (res.status === 204) return undefined as T;   // DELETE has no body
  return (await res.json()) as T;
}

export async function listTasks(): Promise<Task[]> {
  return handle<Task[]>(await fetch(`${BASE_URL}/tasks`));
}

export async function updateTask(id: number, changes: TaskUpdate): Promise<Task> {
  const res = await fetch(`${BASE_URL}/tasks/${id}`, {
    method: "PATCH",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(changes),
  });
  return handle<Task>(res);
}

Three design decisions to notice:

• The generic handle<T> parses success, converts a FastAPI {"detail": …} error into a typed ApiError that carries the status code (so a component can tell 404 from 500), and knows that 204 No Content has no body to parse. Every function funnels through it — the res.ok gotcha is handled once.

• BASE_URL from import.meta.env.VITE_API_URL. The backend’s address is configuration, not a hard-coded string. Vite injects any VITE_-prefixed env var at build time; the ?? "http://127.0.0.1:8000" is the local-dev default. Ship to production by setting VITE_API_URL, no code change.

• Return types are Promise<Task>, Promise<Task[]>, Promise<void>. The typed boundary starts here: everything downstream knows what it’s getting.

11.1 Repository structure🔗

11.2 Testing a React app🔗

Reference material for the project — not lectured. Tests use Vitest (a Vite-native test runner) and Testing Library, which asserts on what the user sees, not on component internals. Two levels:

• api.test.ts stubs the global fetch — no server needed — and checks the client parses tasks, builds query strings, and throws ApiError with the right status on 404. (Same “fake the boundary” idea as the backend’s FakeClient.)

• App.test.tsx mocks the whole ./api module and drives the real UI: it asserts the loading text appears, then the task; that an error shows a Retry that recovers; that the form calls createTask; that the checkbox calls updateTask(1, { done: true }).

it("shows a loading state, then the tasks", async () => {
  vi.mocked(api.listTasks).mockResolvedValue([task]);
  render(<App />);
  expect(screen.getByText(/loading tasks/i)).toBeInTheDocument();     // state 1
  expect(await screen.findByText(/read react notes/i)).toBeInTheDocument(); // state 3
});

Layer the vocabulary as the eval lecture did: type checking proves the code is consistent with the contract (structural, total, free); tests prove it behaves correctly (behavioral, sampled, costs a little). You want both — they fail on different bugs.

11.3 Build & run🔗

# 1. Backend (add CORS from Appendix B first), in the FastAPI project:
uvicorn app.main:app --reload            # http://127.0.0.1:8000

# 2. Frontend:
git clone git@github.com:software-dev-genai/exercises.git
cd exercises/08-terptasks-web

npm install
npm run dev                              # http://localhost:5173

# The checks (what CI runs):
npm run typecheck                        # tsc --noEmit  → the type gate
npm test                                 # vitest run    → 8 passed
npm run build                            # typecheck + production bundle in dist/

Open http://localhost:5173, add a task, check it off, delete it — and watch the requests land in the uvicorn log. That is your full stack, running.

Basic🔗

1. In TaskItem, add the due date next to the course, but only when task.due is not null. Explain why {task.due && <em>…</em>} is the idiomatic way and what would render if you wrote {task.due ? task.due : null} vs. {task.due}.

2. The NewTaskForm submit button is disabled while submitting. Add the same guard so the form can’t be submitted with an empty title or empty course. Which piece of state drives the disable, and where does it live?

3. Explain, in terms of the render loop, why tasks.push(x); setTasks(tasks) fails to update the screen but setTasks([...tasks, x]) works.

4. Line up models.py and types.ts. For each of due, priority, and id, state the Python type, the TypeScript type, and why they differ (if they do).

5. (Appendix B.) You load the page and see a permanent “Loading tasks…” with a CORS error in the console. Which file do you edit to fix it — a React file or a FastAPI file — and why can’t it be fixed in the browser?

Intermediate🔗

• 6. Add a filter UI: a dropdown of courses that calls GET /tasks?course=X. Put the selected course in state, and make the useEffect re-run when it changes (hint: the dependency array). What happens to the loading state on each change?

• 7. Replace the fetch calls in api.ts with Axios (npm install axios). Delete the manual res.ok check and JSON.stringify; move the ApiError translation into an Axios error handler. Keep the public function signatures identical so no component changes. What did you gain and lose?

• 8. Add runtime validation with Zod: define a TaskSchema, and in handle, parse the response with TaskSchema.array().parse(json). Now break the contract (have the server send titel) and observe the difference between the TypeScript cast (silent) and the Zod parse (throws). Which bug does each catch?

• 9. Implement optimistic updates for toggleDone: flip the checkbox in state immediately, fire the PATCH, and roll back if it fails. What new state or error handling does this require, and what does the user experience gain?

• 10. Write a Vitest test for NewTaskForm alone (not through App): render it with a mock onCreate, type a title and course, submit, and assert onCreate was called once with the right TaskCreate. Then assert the form clears only after the promise resolves.

Advanced🔗

• 11. Kill the hand-mirrored types. TerpTasks serves an OpenAPI schema at /openapi.json. Use openapi-typescript to generate types.ts from it as part of npm run build. Now change a field in models.py and show that tsc –noEmit fails on the frontend without anyone editing types.ts by hand. Discuss what this does to the “mirror stays honest” problem — and its new failure mode (schema drift between generation runs).

• 12. Add authenticated requests. Suppose TerpTasks requires a Bearer token (RBAC lecture). Add an Axios interceptor (or a fetch wrapper) that attaches the token to every request and, on a 401, redirects to a login screen — without touching any of the four API functions’ call sites. Explain why the interceptor/wrapper is the right layer, referencing the backend’s dependency-injection pattern.

• 13. Design the loading UX at scale. For a list of 500 tasks with per-row toggles, specify: how you avoid a full-list spinner on every single toggle (per-row pending state), how you prevent a slow toggle from clobbering a newer one (request ordering/cancellation), and how you’d measure whether the UI feels fast (which of the eval lecture’s latency percentiles matter to a user, and where you’d instrument the frontend to capture them).

Key takeaways🔗

1. The UI is a function of state. You declare what the screen looks like for a given state and change state via setters; React does the DOM. You never synchronize by hand — that kills the whole class of “screen disagrees with data” bugs.

2. Data down, events up. Props flow from parent to child and are read-only; children request changes by calling callbacks the parent supplied. Split components into presentational (render props) and container (own state).

3. useState for values, useEffect for the outside world. Never mutate state in place — produce a new array/object. Effects run after render; the dependency array decides when they re-run ([] = once on mount).

4. Types mirror the backend contract. types.ts is a hand-copy of models.py; the tricky translations (date→string|null, enum→string-union, optional-vs-nullable) are where full-stack bugs concentrate. Types are erased at runtime — a cast is a promise, not a check.

5. One typed client module. Centralize fetch/Axios in api.ts; handle the res.ok gotcha and the {"detail"} error shape once; carry the HTTP status in an ApiError. Read the base URL from VITE_API_URL, don’t hard-code it.

6. Every network screen has three states — loading, error, data (and empty is data). Render all of them or ship the “flash of undefined” bug.

7. tsc –noEmit is a CI gate that tests can’t replace. It checks every line against the contract structurally, for free; it caught a real bug in this very project that the passing tests missed. Keep strict: true on.

Terminology🔗

Common mistakes🔗

• Mutating state in place (arr.push) and wondering why the screen doesn’t update.

• Rendering only the happy path — no loading, no error, no empty — and shipping a blank/crashing screen.

• Forgetting fetch resolves on 404/500; treating an error body as data because you skipped res.ok.

• Typing due as Date when JSON delivers a string, or forgetting a field can be null.

• Believing a TypeScript cast validates the response at runtime (it doesn’t; that’s Zod’s job).

• Missing or index-based key on a mapped list, causing wrong-row updates.

• Trying to fix a CORS error in React instead of on the server.

• Turning off strict to silence null errors — deferring the crash to production.

• Treating tsc as optional because “the tests pass” — they check different things.

Connections🔗

• Backward: the FastAPI lecture built the routes and Pydantic models this frontend mirrors; the REST lecture’s verbs/status codes are exactly what api.ts sends and handle interprets; layered architecture reappears as components-vs-hooks; the testing lecture’s fakes and CI gate return as stubbed fetch and tsc –noEmit; the eval lecture’s “gate on every change” is the same discipline, and its latency percentiles reappear in exercise 13.

• Forward: state management beyond one hook (Context, then libraries like Redux/Zustand) when state must be shared across distant components; data-fetching libraries (TanStack Query) that turn §8’s three states + caching into one line; server-side rendering (Next.js); and generating types.ts from OpenAPI (exercise 11) so the mirror can never drift — the industrial answer to the theme of this lecture.