279 lines
7.2 KiB
Markdown
279 lines
7.2 KiB
Markdown
# QuickPoll Next.js 15 Demo Project
|
|
|
|
A complete, step-by-step Next.js 15 polling application built for live-coding classroom demonstrations. Includes git tags at each development step for easy navigation during teaching.
|
|
|
|
## 📦 What's Included
|
|
|
|
### Zip Files (Individual Steps)
|
|
- `stap-0.zip` - Project setup + types + data
|
|
- `stap-1.zip` - Layout & Navigation
|
|
- `stap-2.zip` - Homepage with poll cards
|
|
- `stap-3.zip` - API routes (GET, POST)
|
|
- `stap-4.zip` - Vote API + demo form ⭐
|
|
- `stap-5.zip` - Poll detail page
|
|
- `stap-6.zip` - VoteForm component
|
|
- `stap-7.zip` - Error handling & loading states
|
|
- `stap-8.zip` - Middleware
|
|
- `bonus.zip` - Create poll page
|
|
|
|
### Complete Project
|
|
- `quickpoll-demo-complete.zip` - Full project with complete git history
|
|
|
|
### Documentation
|
|
- `QUICK-START.md` - Instructions for Tim (start here!)
|
|
- `TEACHER-GUIDE.md` - Comprehensive teaching guide
|
|
- `PROJECT-SUMMARY.md` - Technical overview
|
|
- `README.md` - This file
|
|
|
|
## 🚀 Getting Started
|
|
|
|
### Step 1: Extract & Setup
|
|
```bash
|
|
unzip quickpoll-demo-complete.zip
|
|
cd quickpoll-demo
|
|
npm install
|
|
npm run dev
|
|
```
|
|
|
|
### Step 2: Navigate to App
|
|
Open http://localhost:3000 in your browser
|
|
|
|
### Step 3: Jump Between Steps (During Teaching)
|
|
```bash
|
|
# View all available steps
|
|
git tag -l
|
|
|
|
# Jump to any step
|
|
git checkout stap-3
|
|
|
|
# See what changed in this step
|
|
git diff stap-2 stap-3
|
|
|
|
# Go to final version
|
|
git checkout bonus
|
|
```
|
|
|
|
## ✨ Key Features
|
|
|
|
- **9 Development Steps** - Logical progression from setup to full app
|
|
- **API Routes** - Backend routes in `/app/api`
|
|
- **Dynamic Routing** - `/poll/[id]` for individual poll pages
|
|
- **Real-Time Voting** - Vote and see results update instantly
|
|
- **Server Components** - Default Next.js 15 pattern
|
|
- **Client Components** - Interactive VoteForm with state
|
|
- **Error Handling** - Loading skeletons, error boundaries, 404 pages
|
|
- **TypeScript** - Fully typed throughout
|
|
- **Tailwind CSS** - Purple-themed responsive design
|
|
- **Middleware** - Request logging and timing
|
|
- **Demo Form** - Testing interface for API endpoints (stap-4)
|
|
|
|
## 📚 Documentation
|
|
|
|
### For Teachers
|
|
Start with **QUICK-START.md** - has everything you need before class
|
|
|
|
### For Understanding the Project
|
|
Read **PROJECT-SUMMARY.md** - complete technical overview
|
|
|
|
### For Teaching Details
|
|
See **TEACHER-GUIDE.md** - tips, key concepts, troubleshooting
|
|
|
|
## 🎯 Typical Class Flow
|
|
|
|
| Step | Duration | Focus |
|
|
|------|----------|-------|
|
|
| stap-0 to stap-2 | 15 min | File structure, homepage, cards |
|
|
| stap-3 | 10 min | API routes concept |
|
|
| stap-4 | 15 min | ⭐ Vote API demo (show DevTools!) |
|
|
| stap-5 to stap-6 | 15 min | Dynamic pages, voting interface |
|
|
| stap-7 to stap-8 | 10 min | Error handling, middleware |
|
|
| bonus | 10 min | Form handling, creating polls |
|
|
|
|
**Total: ~75 minutes for complete lesson**
|
|
|
|
## 💡 Key Teaching Moments
|
|
|
|
### stap-4: The Demo Form
|
|
This is your star moment! Show:
|
|
1. Demo form at http://localhost:3000/demo
|
|
2. Open DevTools Console - show logging
|
|
3. Switch to Network tab - show POST request
|
|
4. Click "Stem" and watch the request happen
|
|
5. Show the JSON response with updated votes
|
|
|
|
### stap-6: VoteForm Component
|
|
Explain:
|
|
- Why "use client" is needed (state management)
|
|
- How useState tracks selected option
|
|
- How fetch() sends vote to API
|
|
- How component updates when response comes back
|
|
|
|
### All Steps
|
|
Keep showing the running app - live feedback is key!
|
|
|
|
## 📋 What's in Each Step
|
|
|
|
### stap-0: Project Setup
|
|
- Create Next.js with TypeScript + Tailwind
|
|
- Define Poll interfaces
|
|
- Create mock data (3 sample polls)
|
|
- Set up folder structure
|
|
|
|
### stap-1: Layout & Navigation
|
|
- Add navbar with branding
|
|
- Set up global layout
|
|
- Add metadata
|
|
|
|
### stap-2: Homepage
|
|
- Display all polls as cards
|
|
- Show poll stats (option count, vote count)
|
|
- Add links to individual polls
|
|
|
|
### stap-3: API Routes
|
|
- `GET /api/polls` - fetch all polls
|
|
- `GET /api/polls/[id]` - fetch single poll
|
|
- `POST /api/polls` - create new poll
|
|
|
|
### stap-4: Vote API + Demo
|
|
- `POST /api/polls/[id]/vote` - record a vote
|
|
- Demo form at `/demo` for testing
|
|
|
|
### stap-5: Poll Detail Page
|
|
- Dynamic route `/poll/[id]`
|
|
- Dynamic metadata for SEO
|
|
- Show poll questions and options
|
|
|
|
### stap-6: VoteForm Component
|
|
- Client component with voting logic
|
|
- Real-time results with percentage bars
|
|
- Purple gradient progress bars
|
|
|
|
### stap-7: Error Handling
|
|
- Loading skeleton (Suspense)
|
|
- Error boundary component
|
|
- 404 pages
|
|
|
|
### stap-8: Middleware
|
|
- Request logging
|
|
- Timing middleware
|
|
- Route matching
|
|
|
|
### bonus: Create Poll
|
|
- Form to create new polls
|
|
- Dynamic option inputs
|
|
- Form validation
|
|
- Navigation after creation
|
|
|
|
## 🛠 Technology Stack
|
|
|
|
- **Next.js 15** - React framework
|
|
- **TypeScript** - Type-safe JavaScript
|
|
- **Tailwind CSS** - Utility-first CSS
|
|
- **React Hooks** - useState for interactivity
|
|
- **Fetch API** - For API calls
|
|
- **Git** - Version control with tags
|
|
|
|
## 🎨 Design System
|
|
|
|
**Purple Theme:**
|
|
- Primary: `#7c3aed` (purple-500)
|
|
- Hover: `#a855f7` (purple-600)
|
|
- Active: `#9333ea` (purple-700)
|
|
|
|
**Neutral:**
|
|
- Light backgrounds: Gray-50
|
|
- Text: Gray-900
|
|
- Borders: Gray-200
|
|
- Errors: Red-600
|
|
|
|
## ✅ Build & Deployment
|
|
|
|
### Verify Build
|
|
```bash
|
|
npm run build
|
|
```
|
|
|
|
### Deploy to Vercel
|
|
```bash
|
|
npm i -g vercel
|
|
vercel
|
|
```
|
|
|
|
One command deployment! (You need a Vercel account)
|
|
|
|
## 📌 Important Notes
|
|
|
|
### In-Memory Data
|
|
This project uses in-memory JavaScript arrays for data. In production, you'd use:
|
|
- PostgreSQL
|
|
- MongoDB
|
|
- Supabase
|
|
- Firebase
|
|
|
|
### No Authentication
|
|
This project doesn't have user accounts. Real apps would have:
|
|
- User authentication
|
|
- User-specific voting history
|
|
- Admin panels
|
|
|
|
### No Database
|
|
Each time you restart the app, votes reset. That's fine for demos!
|
|
|
|
## 🤔 Common Questions
|
|
|
|
**Q: Is this production-ready?**
|
|
A: No - it's designed for learning. Add a database for production.
|
|
|
|
**Q: Can I modify it for my class?**
|
|
A: Yes! Use it as a starting point for assignments.
|
|
|
|
**Q: How do I extend it?**
|
|
A: Add a real database (PostgreSQL with Prisma is popular), add authentication, add user accounts, etc.
|
|
|
|
**Q: Where can students learn more?**
|
|
A: https://nextjs.org/learn - official Next.js tutorial
|
|
|
|
## 📞 Support
|
|
|
|
Each zip file is independent and self-contained. You can:
|
|
1. Extract any `stap-X.zip` individually
|
|
2. Run `npm install` and `npm run dev`
|
|
3. See the app at that stage of development
|
|
|
|
The `quickpoll-demo-complete.zip` has git history, so you can:
|
|
1. `git log --oneline` - see all commits
|
|
2. `git checkout stap-3` - jump to any step
|
|
3. `git diff stap-2 stap-3` - see what changed
|
|
|
|
## 🎓 For Students
|
|
|
|
After the lesson, students can:
|
|
1. Clone the repo and explore the code
|
|
2. Modify styling with Tailwind
|
|
3. Add new features (poll deletion, editing, etc.)
|
|
4. Connect to a real database
|
|
5. Deploy to Vercel
|
|
|
|
This is a great foundation for learning full-stack web development!
|
|
|
|
## 📝 Notes
|
|
|
|
- All code in English (variable names, comments)
|
|
- UI text in Dutch (button labels, messages)
|
|
- Fully typed TypeScript throughout
|
|
- Comprehensive comments for teaching
|
|
- Clean, readable code style
|
|
|
|
## 🎉 Ready to Teach!
|
|
|
|
You have everything you need. Good luck with your live-coding demonstration!
|
|
|
|
Start with **QUICK-START.md** for immediate instructions.
|
|
|
|
---
|
|
|
|
**Version:** 1.0
|
|
**Next.js:** 15.x
|
|
**Node:** 18+ recommended
|
|
**Date Created:** March 2026
|