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, Vite, TailwindCSS v4 + shadcn/ui, Zustand, TanStack Query v5, and react-router-dom.
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:
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.