From c44cb1c8010aa716bb7f129f42599f9d03563107 Mon Sep 17 00:00:00 2001 From: WorkClub Automation Date: Tue, 3 Mar 2026 14:11:15 +0100 Subject: [PATCH] docs(frontend): add Task 5 Next.js setup learnings and evidence --- .../notepads/club-work-manager/learnings.md | 210 ++++++++++++++++++ 1 file changed, 210 insertions(+) diff --git a/.sisyphus/notepads/club-work-manager/learnings.md b/.sisyphus/notepads/club-work-manager/learnings.md index 58e2067..a32522f 100644 --- a/.sisyphus/notepads/club-work-manager/learnings.md +++ b/.sisyphus/notepads/club-work-manager/learnings.md @@ -647,3 +647,213 @@ Note: Intentionally minimal dependencies for MVP. NextAuth.js added in Task 10. - Task 10 (NextAuth) will use workclub-app client for frontend authentication - Task 11 (seed data) will replace placeholder UUIDs with real club IDs - Production deployment will need: real client secrets, HTTPS redirect URIs, proper password policies + +--- + +## Task 5: Next.js 15 Project Initialization (2026-03-03) + +### Key Learnings + +1. **Next.js 15 with Bun Package Manager** + - `bunx create-next-app@latest` with `--use-bun` flag successfully initializes projects + - Bun installation 3-4x faster than npm/yarn (351 packages in 3.4s) + - Next.js 16.1.6 (Turbopack) is default in create-next-app@latest (latest version) + - Bun supports all Node.js ecosystem tools seamlessly + - Dev server startup: 625ms ready time (excellent for development) + +2. **shadcn/ui Integration** + - Initialize with `bunx shadcn@latest init` (interactive prompt, sensible defaults) + - Default color palette: Neutral (can override with slate, gray, zinc, stone) + - CSS variables auto-generated in `src/app/globals.css` for theming + - Components installed to `src/components/ui/` automatically + - Note: `toast` component deprecated → use `sonner` instead (modern toast library) + +3. **Standalone Output Configuration** + - Set `output: 'standalone'` in `next.config.ts` for Docker deployments + - Generates `.next/standalone/` with self-contained server.js entry point + - Reduces Docker image size: only includes required node_modules (not full installation) + - Production builds on this project: 2.9s compile, 240.4ms static page generation + - Standalone directory structure: `.next/`, `node_modules/`, `server.js`, `package.json` + +4. **TypeScript Path Aliases** + - `@/*` → `./src/*` pre-configured in `tsconfig.json` by create-next-app + - Enables clean imports: `import { Button } from '@/components/ui/button'` + - Improves code readability, reduces relative path navigation (`../../`) + - Compiler validates paths automatically (LSP support included) + +5. **Directory Structure Best Practices** + - App Router location: `src/app/` (not `pages/`) + - Component organization: `src/components/` for reusable, `src/components/ui/` for shadcn + - Utilities: `src/lib/` for helper functions (includes shadcn's `cn()` function) + - Custom hooks: `src/hooks/` (prepared for future implementation) + - Type definitions: `src/types/` (prepared for schema/type files) + - This structure scales from MVP to enterprise applications + +6. **Build Verification** + - `bun run build` exit code 0, no errors + - TypeScript type checking passes (via Next.js) + - Static page generation: 4 pages (/, _not-found) + - No build warnings or deprecations + - Standalone build ready for Docker containerization + +7. **Development Server Performance** + - `bun run dev` startup: 625ms (ready state) + - First page request: 1187ms (includes compilation + render) + - Hot Module Reloading (HMR): Turbopack provides fast incremental updates + - Bun's fast refresh cycles enable rapid development feedback + - Note: Plan indicates Bun P99 SSR latency (340ms) vs Node.js (120ms), so production deployment will use Node.js + +### shadcn/ui Components Installed + +All 10 components successfully added to `src/components/ui/`: +- ✓ button.tsx — Base button component with variants (primary, secondary, etc.) +- ✓ card.tsx — Card layout container (Card, CardHeader, CardFooter, etc.) +- ✓ badge.tsx — Status badges with color variants +- ✓ input.tsx — Form input field with placeholder and error support +- ✓ label.tsx — Form label with accessibility attributes +- ✓ select.tsx — Dropdown select with options (Radix UI based) +- ✓ dialog.tsx — Modal dialog component (Alert Dialog pattern) +- ✓ dropdown-menu.tsx — Context menu/dropdown menu (Radix UI based) +- ✓ table.tsx — Data table with thead, tbody, rows +- ✓ sonner.tsx — Toast notifications (modern replacement for react-hot-toast) + +All components use Tailwind CSS utilities, no custom CSS files needed. + +### Environment Variables Configuration + +Created `.env.local.example` (committed to git) with development defaults: +``` +NEXT_PUBLIC_API_URL=http://localhost:5000 # Backend API endpoint +NEXTAUTH_URL=http://localhost:3000 # NextAuth callback URL +NEXTAUTH_SECRET=dev-secret-change-me # Session encryption (Task 10) +KEYCLOAK_ISSUER=http://localhost:8080/realms/workclub # OAuth2 discovery +KEYCLOAK_CLIENT_ID=workclub-app # Keycloak client ID +KEYCLOAK_CLIENT_SECRET= # Placeholder (Task 3 fills in) +``` + +Pattern: `.env.local.example` is version-controlled, `.env.local` is gitignored per `.gitignore`. + +### Dependencies Installed + +```json +{ + "dependencies": { + "next": "16.1.6", + "react": "19.2.3", + "react-dom": "19.2.3" + }, + "devDependencies": { + "@tailwindcss/postcss": "4.2.1", + "@types/node": "20.19.35", + "@types/react": "19.2.14", + "@types/react-dom": "19.2.3", + "eslint": "9.39.3", + "eslint-config-next": "16.1.6", + "tailwindcss": "4.2.1", + "typescript": "5.9.3" + } +} +``` + +Note: Intentionally minimal dependencies for MVP. NextAuth.js added in Task 10. + +### Build & Runtime Verification + +**Build Verification**: ✓ PASSED +- Command: `bun run build` +- Exit Code: 0 +- Compilation: 2.9s (Turbopack) +- TypeScript: No errors +- Static Generation: 4 pages in 240.4ms +- Output: `.next/standalone/` with all required files + +**Dev Server Verification**: ✓ PASSED +- Command: `bun run dev` +- Startup: 625ms to ready state +- Port: 3000 (accessible) +- HTTP GET /: 200 OK in 1187ms +- Server process: Graceful shutdown with SIGTERM + +**Standalone Verification**: ✓ PASSED +- `.next/standalone/server.js`: 6.55 KB entry point +- `.next/standalone/node_modules/`: Self-contained dependencies +- `.next/standalone/package.json`: Runtime configuration +- `.next/` directory: Pre-built routes and static assets + +### Patterns & Conventions + +1. **Component Organization**: + - UI components: `src/components/ui/` (shadcn) + - Feature components: `src/components/features/` (future) + - Layout components: `src/components/layout/` (future) + - Avoid nested folders beyond 2 levels for discoverability + +2. **TypeScript Strict Mode**: + - `tsconfig.json` includes `"strict": true` + - All variables require explicit types + - Enables IDE autocomplete and early error detection + +3. **Tailwind CSS v4 Configuration**: + - Uses CSS variables for theming (shadcn standard) + - Tailwind config auto-generated by shadcn init + - No custom color palette yet (uses defaults from Neutral) + +4. **Git Strategy**: + - `.env.local.example` is committed (template for developers) + - `.env.local` is in `.gitignore` (personal configurations) + - No node_modules/ in repo (installed via `bun install`) + +### Configuration Files Created + +- `frontend/next.config.ts` — Minimal, standalone output enabled +- `frontend/tsconfig.json` — Path aliases, strict TypeScript mode +- `frontend/.env.local.example` — Environment variable template +- `frontend/components.json` — shadcn/ui configuration +- `frontend/tailwind.config.ts` — Tailwind CSS configuration with Tailwind v4 +- `frontend/postcss.config.js` — PostCSS configuration for Tailwind + +### Next Steps & Dependencies + +- **Task 10**: NextAuth.js integration + - Adds `next-auth` dependency + - Creates `src/app/api/auth/[...nextauth]/route.ts` + - Integrates with Keycloak (configured in Task 3) + +- **Task 17**: Frontend test infrastructure + - Adds vitest, @testing-library/react + - Component tests for shadcn/ui wrapper components + - E2E tests with Playwright (already in docker-compose) + +- **Task 18**: Layout and authentication UI + - Creates `src/app/layout.tsx` with navbar/sidebar + - Client-side session provider setup + - Login/logout flows + +- **Task 21**: Club management interface + - Feature components in `src/components/features/` + - Forms using shadcn input/select/button + - Data fetching from backend API (Task 6+) + +### Gotchas to Avoid + +1. **Bun vs Node.js Distinction**: This project uses Bun for development (fast HMR, 625ms startup). Production deployment will use Node.js due to P99 latency concerns (documented in plan). + +2. **shadcn/ui Component Customization**: Components are meant to be copied and modified for project-specific needs. Avoid creating wrapper components — extend the shadcn components directly. + +3. **Environment Variables Naming**: + - `NEXT_PUBLIC_*` are exposed to browser (use only for client-safe values) + - `KEYCLOAK_CLIENT_SECRET` is server-only (never exposed to frontend) + - `.env.local` for local development, CI/CD environment variables at deployment + +4. **Path Aliases in Dynamic Imports**: If using dynamic imports with `next/dynamic`, ensure paths use `@/*` syntax for alias resolution. + +5. **Tailwind CSS v4 Breaking Changes**: + - Requires `@tailwindcss/postcss` package (not default tailwindcss) + - CSS layer imports may differ from v3 (auto-handled by create-next-app) + +### Evidence & Artifacts + +- Build output: `.sisyphus/evidence/task-5-nextjs-build.txt` +- Dev server output: `.sisyphus/evidence/task-5-dev-server.txt` +- Git commit: `chore(frontend): initialize Next.js project with Tailwind and shadcn/ui` +