gh-hopeoverture-worldbuilding-app-skills-plugins-nextjs-fullstack-scaffold/skills/nextjs-fullstack-scaffold/references/implementation-checklist.md

# Implementation Checklist

Complete checklist for scaffolding a Next.js full-stack application.

## Phase 1: Project Setup

### Configuration Files
- [ ] `package.json` - Dependencies and scripts
- [ ] `tsconfig.json` - TypeScript configuration
- [ ] `next.config.ts` - Next.js configuration
- [ ] `tailwind.config.ts` - Tailwind CSS + shadcn/ui
- [ ] `postcss.config.mjs` - PostCSS configuration
- [ ] `eslint.config.mjs` - ESLint v9 flat config
- [ ] `prettier.config.js` - Prettier configuration
- [ ] `.gitignore` - Git ignore patterns
- [ ] `.env.example` - Environment variables template
- [ ] `README.md` - Setup instructions

### Testing Configuration
- [ ] `vitest.config.ts` - Vitest configuration
- [ ] `playwright.config.ts` - Playwright configuration
- [ ] Set up test directories (`tests/unit`, `tests/integration`, `tests/e2e`)

### Git Hooks
- [ ] Initialize Husky (`npx husky init`)
- [ ] Add pre-commit hook for lint-staged
- [ ] Configure lint-staged in package.json

## Phase 2: Folder Structure

### App Router Structure
- [ ] `app/layout.tsx` - Root layout
- [ ] `app/page.tsx` - Home page
- [ ] `app/globals.css` - Global styles with Tailwind
- [ ] `app/(auth)/login/page.tsx` - Login page
- [ ] `app/(auth)/layout.tsx` - Auth layout
- [ ] `app/(protected)/dashboard/page.tsx` - Dashboard
- [ ] `app/(protected)/profile/page.tsx` - User profile
- [ ] `app/(protected)/data/page.tsx` - Data table page
- [ ] `app/(protected)/layout.tsx` - Protected layout
- [ ] `app/api/data/route.ts` - Example API route
- [ ] `middleware.ts` - Auth middleware

### Components
- [ ] `components/providers.tsx` - App providers (Toaster, etc.)
- [ ] `components/layout/header.tsx` - Header component
- [ ] `components/layout/sidebar.tsx` - Sidebar component
- [ ] `components/layout/nav.tsx` - Navigation component
- [ ] `components/auth/login-form.tsx` - Login form with RHF + Zod
- [ ] `components/auth/auth-button.tsx` - Login/logout button
- [ ] `components/dashboard/stats-card.tsx` - Stats card component
- [ ] `components/dashboard/data-table.tsx` - Data table component

### shadcn/ui Components
- [ ] `components/ui/button.tsx`
- [ ] `components/ui/card.tsx`
- [ ] `components/ui/input.tsx`
- [ ] `components/ui/label.tsx`
- [ ] `components/ui/form.tsx`
- [ ] `components/ui/table.tsx`
- [ ] `components/ui/dropdown-menu.tsx`
- [ ] `components/ui/avatar.tsx`

### Lib Files
- [ ] `lib/utils.ts` - Utility functions (cn, etc.)
- [ ] `lib/prisma.ts` - Prisma client singleton
- [ ] `lib/supabase/client.ts` - Supabase client for client components
- [ ] `lib/supabase/server.ts` - Supabase client for server components
- [ ] `lib/supabase/middleware.ts` - Supabase middleware helper
- [ ] `lib/actions/auth.ts` - Auth server actions
- [ ] `lib/actions/user.ts` - User server actions
- [ ] `lib/actions/data.ts` - Data server actions
- [ ] `lib/validations/auth.ts` - Auth validation schemas
- [ ] `lib/validations/user.ts` - User validation schemas
- [ ] `lib/validations/data.ts` - Data validation schemas

### Database
- [ ] `prisma/schema.prisma` - Prisma schema
- [ ] `prisma/seed.ts` - Database seed script

## Phase 3: Core Features

### Authentication
- [ ] Supabase auth setup (server + client)
- [ ] Login form with email/password
- [ ] Server action for sign in
- [ ] Server action for sign out
- [ ] Middleware for protected routes
- [ ] Auth state management
- [ ] Redirect logic after login/logout

### Protected Routes
- [ ] Dashboard page with data fetching
- [ ] Profile page with user info
- [ ] Data table page with CRUD operations
- [ ] Server actions for mutations
- [ ] Form validation with Zod
- [ ] Toast notifications on success/error

### UI Components
- [ ] Responsive layout with header/sidebar
- [ ] Dark mode toggle (optional)
- [ ] Loading states with Suspense
- [ ] Error boundaries
- [ ] Accessible forms with shadcn/ui

### Database Integration
- [ ] Prisma schema with User model
- [ ] Prisma schema with example data model
- [ ] Database migrations
- [ ] Seed script with sample data
- [ ] Prisma client queries in server components
- [ ] Server actions with database mutations

## Phase 4: Testing

### Unit Tests
- [ ] `tests/unit/utils.test.ts` - Test utility functions
- [ ] Test Zod validation schemas
- [ ] Test helper functions

### Integration Tests
- [ ] `tests/integration/auth.test.tsx` - Test auth components
- [ ] Test form submissions
- [ ] Test server actions

### E2E Tests
- [ ] `tests/e2e/login.spec.ts` - Test login flow
- [ ] Test protected route access
- [ ] Test form submission flows
- [ ] Test navigation

## Phase 5: CI/CD

### GitHub Actions
- [ ] `.github/workflows/ci.yml` - CI workflow
- [ ] Run linting
- [ ] Run type checking
- [ ] Run tests
- [ ] Run build
- [ ] Set up Vercel deployment (optional)

## Phase 6: Documentation

### README Sections
- [ ] Project overview
- [ ] Tech stack list
- [ ] Prerequisites
- [ ] Installation steps
- [ ] Environment variable setup
- [ ] Database setup (Prisma)
- [ ] Supabase setup instructions
- [ ] Running locally
- [ ] Testing commands
- [ ] Deployment instructions
- [ ] Folder structure explanation
- [ ] Contributing guidelines (optional)

## Verification Steps

After scaffolding, verify:

1. **Dependencies Install**: `npm install` completes without errors
2. **Type Checking**: `npx tsc --noEmit` passes
3. **Linting**: `npm run lint` passes
4. **Formatting**: `npm run format:check` passes
5. **Build**: `npm run build` succeeds
6. **Tests**: `npm test` passes
7. **E2E Tests**: `npm run test:e2e` passes (with test environment)
8. **Dev Server**: `npm run dev` starts successfully
9. **Prisma**: `npx prisma generate` works
10. **Git Hooks**: Commit triggers lint-staged

## Common Issues & Solutions

### Issue: Prisma client not generated
**Solution**: Run `npx prisma generate` after schema changes

### Issue: Supabase auth not working
**Solution**: Check environment variables and cookie configuration

### Issue: ESLint errors
**Solution**: Run `npm run lint -- --fix` to auto-fix

### Issue: Type errors
**Solution**: Ensure all dependencies are installed and Prisma is generated

### Issue: Build fails
**Solution**: Check for missing environment variables and type errors

### Issue: Tests fail
**Solution**: Ensure test environment is properly configured in vitest.config.ts

## Post-Scaffold Tasks

After completing the scaffold:

1. **Environment Setup**: Copy `.env.example` to `.env` and fill in values
2. **Supabase Project**: Create Supabase project and get credentials
3. **Database Schema**: Run `npx prisma db push` to sync schema
4. **Seed Data**: Run `npm run db:seed` to populate sample data
5. **Install shadcn/ui**: Run initialization commands for components
6. **Git Init**: Initialize git repository and make first commit
7. **Deploy**: Connect to Vercel and deploy
8. **Test**: Verify all features work in production

## Optional Enhancements

Consider adding these after the base scaffold:

- [ ] Email verification flow
- [ ] Password reset flow
- [ ] User roles and permissions
- [ ] Multi-factor authentication
- [ ] File upload with Supabase Storage
- [ ] Real-time subscriptions
- [ ] Advanced data table features (export, filters)
- [ ] User preferences/settings page
- [ ] Activity logs/audit trail
- [ ] API documentation
- [ ] Storybook for components
- [ ] Performance monitoring
- [ ] Error tracking (Sentry)
- [ ] Analytics integration