PawFinder — React Hackday

Build a real animal re-homing app in one day. By the end you'll have a working React application with a component library, real API data, and a full test suite.

---

What you'll build

PawFinder — a web app where you can browse animals available for adoption, filter by species, search by name, view individual animal profiles, and submit adoption enquiries.

The app fetches data from a local Express API serving 34 animals: dogs, cats, rabbits, guinea pigs, and a 25-year-old tortoise named Sheldon.

---

Prerequisites

Before the day, make sure you have:

• Node.js v20 or higher — check with node -v
• npm v10 or higher — check with npm -v
• VS Code — with the ESLint and Prettier extensions recommended
• Git — check with git --version

No prior React experience needed. Some JavaScript or TypeScript experience is helpful.

---

Getting started

1. Clone the repository

git clone <repo-url>
cd react-tutorial

2. Install dependencies

You need to install dependencies for both the web app and the API:

# Web app (run from the root)
npm install

# Animals API
cd services/animals-api
npm install
cd ../..

3. Start the Animals API

Open a terminal and leave it running:

cd services/animals-api
npm start

You should see:

PawFinder Animals API running at http://localhost:3001

Verify it's working: open http://localhost:3001/animals in your browser. You should see animal data.

4. Start the web app

Open a second terminal:

npm run dev

Open http://localhost:5173. You should see the PawFinder header.

5. Reset to the beginning

npm run section:1:start

You're ready. Open the Section 1 worksheet and start building.

---

Workshop sections

#	Section	Worksheet
1	React Fundamentals — components, JSX, props	worksheets/section-1-react-fundamentals.md
2	State & Interactivity — search and filter	worksheets/section-2-state-interactivity.md
3	Atomic Design + Storybook — component library	worksheets/section-3-atomic-design-storybook.md
4	Data Fetching — real API, loading states, routing	worksheets/section-4-data-fetching.md
5	Unit & Component Testing — Vitest + RTL + MSW	worksheets/section-5-testing.md
6	E2e Testing with Playwright (stretch)	worksheets/section-6-e2e-stretch.md

---

Useful commands

Command	What it does
npm run dev	Start the web app at http://localhost:5173
npm run storybook	Start Storybook at http://localhost:6006
npm test	Run unit and component tests in watch mode
npm run test:e2e:ui	Run Playwright tests in visual mode
npm run section:N:start	Reset your code to the beginning of section N
npm run section:N:complete	Reset your code to the end of section N

---

Stuck? Use the reference code

Every section has a complete reference solution. You can view it without affecting your working code:

sections/
  section-1/
    start/     ← the state of src/ at the beginning of section 1
    complete/  ← the full solution for section 1
  section-2/
    ...

Open any file in sections/section-N/complete/ directly in VS Code to read the solution.

To reset your working code to a known-good state:

npm run section:2:start   # wipes src/ and replaces it with section 2's start state

You won't lose anything that isn't already in the sections/ snapshots — but make sure you've read or saved any code you want to keep before running a reset.

---

Project structure

react-tutorial/
├── src/                     # Your working files — edit these
│   ├── components/          # UI components (grows across sections)
│   ├── hooks/               # Custom React hooks (section 4+)
│   ├── pages/               # Route-level components (section 4+)
│   ├── services/            # API client functions (pre-built)
│   ├── types/               # TypeScript interfaces (pre-built)
│   ├── data/                # Sample data for sections 1–3
│   └── test/                # MSW handlers and test setup (pre-built)
│
├── sections/                # Read-only reference snapshots — don't edit
│
├── services/
│   └── animals-api/         # Express mock API — leave running, don't edit
│
├── worksheets/              # Step-by-step instructions for each section
├── facilitator-guide.md     # For the person running the day
└── hackday-spec.md          # Full event specification

---

Tech stack

Tool	Purpose
Vite + React 19 + TypeScript	Build tooling and UI framework
Tailwind CSS v4	Styling
React Router v7	Client-side routing (section 4)
Storybook 8	Component documentation (section 3)
Vitest	Unit and component test runner (section 5)
React Testing Library	Component testing utilities (section 5)
MSW v2	API mocking in tests (section 5)
Playwright	End-to-end browser tests (section 6)
Express	Mock Animals API

---

Animals API reference

The API runs on http://localhost:3001 and is automatically proxied via /api in the dev server.

Endpoint	Description
GET /api/animals	List all animals. Supports ?species=dog, ?status=available, ?search=golden
GET /api/animals/:id	Single animal by ID
POST /api/enquiries	Submit an adoption enquiry

The API serves 34 animals: 12 dogs, 10 cats, 6 rabbits, 4 guinea pigs, and 2 other (a parrot and a tortoise). Each animal has rich story, healthNotes, and rehomingAdvice fields — designed for a future hackday adding local LLM chat.