Building AI-Powered Interfaces with Modern React

Build one React AI interface in four layers: streaming, tools, typed React UI, and production-ready interaction patterns.

The repository root is the workshop starter. The completed reference is in steps/04-production/.

Getting started

Requires Node.js 20.9+ and pnpm.

git clone https://github.com/aurorascharff/ai-react-workshop.git
cd ai-react-workshop
pnpm install
pnpm dev

Open http://localhost:3000.

Workshop format

Keep the repository root open while you work:

1. Open the current file in exercises/. It describes the problem, the outcome, and the few files you need to change.
2. Try the exercise in the root app.
3. If you get stuck or want to compare approaches, open the matching reference solution in exercises/solutions/. It contains the exact code and explains why it works.
4. The apps in steps/ are runnable checkpoints after each exercise. They do not apply changes to your app. Use them to compare behavior, catch up, or demo the finished state while you keep editing the root app.

Visual components, mock data, request validation, persistence, and safe error helpers are provided. The exercises stay focused on the React and AI SDK decisions being taught.

Optional OpenAI key

The workshop works without a key by using its built-in mock assistant. To use OpenAI instead:

1. Create a key in the OpenAI API Keys dashboard.

2. Create .env.local:

   OPENAI_API_KEY=your_key_here
   OPENAI_MODEL=gpt-5.6-terra

3. Restart pnpm dev.

API billing is separate from ChatGPT. Add credits or check spend limits in the OpenAI billing overview. Never commit .env.local.

Mock mode can also be selected explicitly:

MOCK_AI=1 # Always use the mock assistant
MOCK_AI=0 # Require the live API

Exercises

Module	What we build	Exercise
1	Stream text as it arrives	Stream AI responses
2	Give the model typed server-side tools	Give the model tools
3	Render streamed tool states with React components	Render results as React UI
4	Add cancellation, persistence, and error paths	Make it production-ready

The exercise is the assignment. The reference solution is the detailed answer. The checkpoint is the runnable result.

Agent structure

The small agent/ directory is inspired by Eve, where an agent grows from focused instructions into optional configuration, tools, and skills:

agent/
├── agent.ts                  model and provider configuration
├── instructions.ts           always-on behavior and safety rules
├── tools/                    narrow server-side capabilities
└── skills/                   reusable workflows loaded when relevant

Exercise Two adds the tools and the release-readiness skill. This workshop uses AI SDK directly rather than Eve, but keeps the same separation so the route does not become one large file. The data functions under lib/ stand in for authenticated application services that tools would call in a real product.

Checkpoints

Each checkpoint is a standalone Next.js app that shares the dependencies installed at the repository root. Enter the checkpoint you want to inspect, then run it normally:

cd steps/04-production
pnpm dev

The same command works inside 00-starter, 01-streaming, 02-tools, and 03-generative-ui. Stop the current server before switching checkpoints. To compare a checkpoint beside your work, give it another port:

pnpm dev --port 3001

The snapshots run independently from 00-starter through 04-production. Install dependencies once at the repository root. Every checkpoint reads the repository root .env.local; none of them modifies the starter you are editing.

Commands

pnpm dev
pnpm check
pnpm build
pnpm build:steps

pnpm check includes every checkpoint typecheck. Run pnpm build:steps before hosting to build all five standalone apps.

The instructor schedule and module notes are in WORKSHOP.md.