docs(frontend): add Task 5 Next.js setup learnings and evidence
This commit is contained in:
WorkClub Automation
@@ -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 10 (NextAuth) will use workclub-app client for frontend authentication
|
||||||
- Task 11 (seed data) will replace placeholder UUIDs with real club IDs
|
- 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
|
- 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=<from-keycloak> # 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`
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user