# Step 1 — Why React + TypeScript for a Frontend

Welcome. This is a hands-on, twelve-step tutorial that takes you from "I've heard React is popular" to "I understand how a real, production TypeScript frontend is put together." Every concept is grounded in **iKanban's own frontend**: [React 18](https://react.dev), [Vite](https://vitejs.dev), [TailwindCSS v4](https://tailwindcss.com) + [shadcn/ui](https://ui.shadcn.com), [Zustand](https://github.com/pmndrs/zustand), [TanStack Query v5](https://tanstack.com/query), and [react-router-dom](https://reactrouter.com).

## What you'll build

Two parts, twelve steps:

| Part | Steps | Focus |
|---|---|---|
| 1 — Frontend Only | 1–6 | React + TypeScript fundamentals, read straight from iKanban components |
| 2 — Frontend + Backend | 7–12 | Trace one real, shipped feature (**Tags**) from Postgres to the rendered dialog |

By the end of Part 2 you'll have followed a single tag — its color, its name, its content — all the way from a SQL row in `crates/remote/src/db/tags.rs` to a `<TagEditDialog>` on screen, and you'll know how to reproduce that trace for any feature in this codebase.

## Why React + TypeScript for a UI like this?

iKanban's frontend is a kanban board, task views, real-time chat, and an AI agent activity feed — a lot of interactive, frequently-changing UI state. Two properties make React + TypeScript a good fit:

### 1. Components as the unit of reuse

A `<Badge>`, a `<Tooltip>`, a `<Dialog>` — each is a small function that takes props and returns JSX. Complex screens (a task detail panel, a settings page) are built by composing dozens of these small pieces rather than one big template. You'll see this directly in Step 4 when we open `AgentModeBadge.tsx`.

### 2. Types catch the bug before the browser does

TypeScript's structural typing means a `Tag` object shaped wrong, a prop passed with the wrong type, or a hook called with a missing argument is a **red squiggle in your editor**, not a blank screen in production. In Part 2 you'll watch this guarantee flow through five layers: a Rust struct, a hand-maintained `.ts` type file, an API client, a React Query hook, and a component — all agreeing on the same shape.

## The honest trade-off

- JSX mixes markup and logic — it reads oddly until it doesn't.
- TypeScript's type system has real depth (generics, discriminated unions, utility types) — Step 2 covers the subset you actually need.
- Client-side state management (local component state vs. Zustand vs. server state via TanStack Query) is a real design decision, not a formality — Steps 5 and 6 explain when to reach for each.

## What you need installed

- **Node.js** (LTS) and a package manager — iKanban uses `pnpm`.
- Any editor with TypeScript language support (VS Code works out of the box).

Check your install:

```bash
node --version    # e.g. v20.x
pnpm --version    # e.g. 9.x
```

When you're ready, continue to **Step 2 — TypeScript Essentials for React**, where we cover the exact TypeScript patterns iKanban's components use every day.