feat: comprehensive boilerplate improvements

Security & Stability: - Add Next.js 16 proxy.ts for BetterAuth cookie-based auth protection - Add rate limiting for API routes (src/lib/rate-limit.ts) - Add Zod validation for chat API request bodies - Add session auth check to chat and diagnostics endpoints - Add security headers in next.config.ts (CSP, X-Frame-Options, etc.) - Add file upload validation and sanitization in storage.ts Core UX Components: - Add error boundaries (error.tsx, not-found.tsx, chat/error.tsx) - Add loading states (skeleton.tsx, spinner.tsx, loading.tsx files) - Add toast notifications with Sonner - Add form components (input.tsx, textarea.tsx, label.tsx) - Add database indexes for performance (schema.ts) - Enhance chat UX: timestamps, copy-to-clipboard, thinking indicator, error display, localStorage message persistence Polish & Accessibility: - Add Open Graph and Twitter card metadata - Add JSON-LD structured data for SEO - Add sitemap.ts, robots.ts, manifest.ts - Add skip-to-content link and ARIA labels in site-header - Enable profile page quick action buttons with dialogs - Update Next.js 15 references to Next.js 16 Developer Experience: - Add GitHub Actions CI workflow (lint, typecheck, build) - Add Prettier configuration (.prettierrc, .prettierignore) - Add .nvmrc pinning Node 20 - Add ESLint rules: import/order, react-hooks/exhaustive-deps - Add stricter TypeScript settings (exactOptionalPropertyTypes, noImplicitOverride) - Add interactive setup script (scripts/setup.ts) - Add session utility functions (src/lib/session.ts) All changes mirrored to create-agentic-app/template/ 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-30 14:46:15 +02:00
parent 1121258238
commit a3a151c67a
125 changed files with 5088 additions and 493 deletions
--- a/specs/boilerplate-improvements/implementation-plan.md
+++ b/specs/boilerplate-improvements/implementation-plan.md
@@ -0,0 +1,165 @@
+# Next.js 16 Boilerplate Improvements - Implementation Plan
+
+## Phase 1: Critical Security & Stability (19 files)
+
+### Security Configuration
+- [ ] Update `next.config.ts` - Add security headers, image config, compression
+- [ ] Modify `package.json` - Remove `@ai-sdk/openai` dependency
+- [ ] Create `src/proxy.ts` - Server-side auth protection using Next.js 16 proxy + BetterAuth
+- [ ] Modify `src/app/api/chat/route.ts` - Add session authentication check
+- [ ] Update `docs/technical/ai/streaming.md` - Fix OpenRouter references
+
+### Next.js 15 → 16 Updates (Main Project)
+- [ ] Update `CLAUDE.md` - Change Next.js 15 to Next.js 16
+- [ ] Update `README.md` - Change Next.js 15 to Next.js 16
+- [ ] Update `docs/business/starter-prompt.md` - Change Next.js 15 to Next.js 16
+- [ ] Update `src/components/starter-prompt-modal.tsx` - Change Next.js 15 to Next.js 16
+- [ ] Update `.claude/agents/polar-payments-expert.md` - Change Next.js 15 to Next.js 16
+- [ ] Update `.claude/agents/better-auth-expert.md` - Change Next.js 15 to Next.js 16
+
+### Next.js 15 → 16 Updates (create-agentic-app Template)
+- [ ] Update `create-agentic-app/README.md` - Change Next.js 15 to Next.js 16
+- [ ] Update `create-agentic-app/template/CLAUDE.md` - Change Next.js 15 to Next.js 16
+- [ ] Update `create-agentic-app/template/README.md` - Change Next.js 15 to Next.js 16
+- [ ] Update `create-agentic-app/template/docs/business/starter-prompt.md` - Change Next.js 15 to Next.js 16
+- [ ] Update `create-agentic-app/template/src/components/starter-prompt-modal.tsx` - Change Next.js 15 to Next.js 16
+- [ ] Update `create-agentic-app/template/.claude/agents/better-auth-expert.md` - Change Next.js 15 to Next.js 16
+- [ ] Update `create-agentic-app/template/.claude/agents/polar-payments-expert.md` - Change Next.js 15 to Next.js 16
+
+---
+
+## Phase 2: Core UX Components (12 files)
+
+### Error Handling
+- [ ] Create `src/app/error.tsx` - Global error boundary
+- [ ] Create `src/app/not-found.tsx` - Custom 404 page
+- [ ] Create `src/app/chat/error.tsx` - Chat-specific error handling
+
+### Loading States
+- [ ] Create `src/components/ui/skeleton.tsx` - Skeleton loading component (via shadcn)
+- [ ] Create `src/components/ui/spinner.tsx` - Loading spinner component
+
+### Toast Notifications
+- [ ] Install shadcn Sonner: `npx shadcn@latest add sonner`
+- [ ] Modify `src/app/layout.tsx` - Add `<Toaster />` component
+
+### Form Components
+- [ ] Install shadcn input: `npx shadcn@latest add input`
+- [ ] Install shadcn textarea: `npx shadcn@latest add textarea`
+- [ ] Install shadcn label: `npx shadcn@latest add label`
+
+### Chat UX Improvements
+- [ ] Modify `src/app/chat/page.tsx`:
+  - [ ] Add message timestamps
+  - [ ] Add copy-to-clipboard for AI responses
+  - [ ] Add typing/thinking indicator during streaming
+  - [ ] Add error display for API failures
+  - [ ] Add message persistence (localStorage)
+
+### Database Schema
+- [ ] Modify `src/lib/schema.ts` - Add missing indexes:
+  - [ ] Index on `session.user_id`
+  - [ ] Index on `session.token`
+  - [ ] Index on `account.user_id`
+  - [ ] Index on `account(provider_id, account_id)`
+  - [ ] Index on `user.email`
+- [ ] Run `pnpm db:generate` to create migration
+- [ ] Run `pnpm db:migrate` to apply migration
+
+---
+
+## Phase 3: Polish & Security (8 files)
+
+### ESLint Configuration
+- [ ] Modify `eslint.config.mjs`:
+  - [ ] Add import ordering rules
+  - [ ] Add TypeScript-eslint rules
+  - [ ] Add React hooks exhaustive-deps
+  - [ ] Add no-console warnings
+
+### API Hardening
+- [ ] Modify `src/app/api/chat/route.ts`:
+  - [ ] Add rate limiting (10 requests/minute per user)
+  - [ ] Add Zod validation for messages
+  - [ ] Add message length limits
+- [ ] Modify `src/app/api/diagnostics/route.ts` - Restrict to authenticated admins
+
+### SEO
+- [ ] Modify `src/app/layout.tsx` - Add Open Graph metadata
+- [ ] Create `src/app/sitemap.ts` - Dynamic sitemap
+- [ ] Create `src/app/robots.ts` - Robots configuration
+
+### Accessibility
+- [ ] Modify `src/components/site-header.tsx`:
+  - [ ] Add `<nav>` role
+  - [ ] Add aria-labels to interactive elements
+  - [ ] Add skip-to-content link
+
+### TypeScript
+- [ ] Modify `tsconfig.json`:
+  - [ ] Add `noUncheckedIndexedAccess: true`
+  - [ ] Add `noImplicitOverride: true`
+  - [ ] Add `exactOptionalPropertyTypes: true`
+
+---
+
+## Phase 4: DevEx & Infrastructure (7 files)
+
+### Code Formatting
+- [ ] Create `.prettierrc` - Prettier configuration
+
+### CI/CD
+- [ ] Create `.github/workflows/ci.yml`:
+  - [ ] Lint check (`pnpm lint`)
+  - [ ] Type check (`pnpm typecheck`)
+  - [ ] Build verification (`pnpm build`)
+  - [ ] Trigger on PR and push to main
+
+### Node Version
+- [ ] Create `.nvmrc` - Pin to Node 20 LTS
+
+### CLI Scripts
+- [ ] Modify `package.json`:
+  - [ ] Add `validate-env` script
+  - [ ] Add `check` script (lint + typecheck)
+
+### Setup Experience
+- [ ] Create `scripts/setup.ts` - Interactive setup wizard:
+  - [ ] Check Node version
+  - [ ] Copy env.example to .env
+  - [ ] Validate required variables
+  - [ ] Offer to run db:migrate
+  - [ ] Provide next steps guidance
+
+### File Storage Security
+- [ ] Modify `src/lib/storage.ts`:
+  - [ ] Add file type whitelist (images, documents)
+  - [ ] Add file size limits (5MB default)
+  - [ ] Add filename sanitization
+
+### Profile Page
+- [ ] Modify `src/app/profile/page.tsx`:
+  - [ ] Enable Edit Profile button with modal
+  - [ ] Enable basic security settings view
+
+---
+
+## Summary
+
+| Phase | Files | Focus |
+|-------|-------|-------|
+| Phase 1 | 19 | Security, stability, Next.js 16 updates |
+| Phase 2 | 12 | Core UX components |
+| Phase 3 | 8 | Polish & security |
+| Phase 4 | 7 | DevEx & infrastructure |
+| **Total** | **46** | |
+
+## Implementation Order
+
+Execute phases sequentially: **Phase 1** → **Phase 2** → **Phase 3** → **Phase 4**
+
+Each phase builds on the previous one:
+1. Phase 1 ensures security and stability
+2. Phase 2 adds core user experience
+3. Phase 3 polishes and hardens
+4. Phase 4 improves developer experience
--- a/specs/boilerplate-improvements/requirements.md
+++ b/specs/boilerplate-improvements/requirements.md
@@ -0,0 +1,131 @@
+# Next.js 16 Boilerplate Improvements - Requirements
+
+## Overview
+
+Comprehensive review and improvement of the Next.js 16 boilerplate project to enhance security, user experience, developer experience, and overall code quality.
+
+## User Decisions
+
+- **Scope:** Full implementation (all improvements including CI/CD, CLI tools)
+- **Testing:** Skip testing framework (keep boilerplate minimal)
+- **Toast Library:** shadcn Sonner component
+- **CI/CD:** Full GitHub Actions pipeline (lint, typecheck, build)
+- **Dockerfile:** Skip (deploying to Vercel only)
+- **Database Seed:** Skip (developers will create their own data)
+
+## Requirements by Category
+
+### 1. Security & Stability (Critical)
+
+1. **next.config.ts** - Currently empty, needs:
+   - Security headers (CSP, X-Frame-Options, X-Content-Type-Options)
+   - Image optimization configuration
+   - Compression settings
+
+2. **Unused Dependency** - Remove `@ai-sdk/openai` from package.json (project uses OpenRouter exclusively)
+
+3. **Server-Side Auth Protection** - Create `src/proxy.ts` using Next.js 16 proxy pattern with BetterAuth for protected routes (`/chat`, `/dashboard`, `/profile`)
+
+4. **API Authentication** - Add session validation to `/api/chat` endpoint to prevent unauthorized API usage
+
+5. **Documentation Consistency** - Update `docs/technical/ai/streaming.md` to use `@openrouter/ai-sdk-provider` instead of `@ai-sdk/openai`
+
+6. **Next.js Version References** - Update all "Next.js 15" references to "Next.js 16" across 14 files
+
+### 2. Core UX Components (High Priority)
+
+1. **Error Handling UI**
+   - Global error boundary (`src/app/error.tsx`)
+   - Custom 404 page (`src/app/not-found.tsx`)
+   - Chat-specific error handling (`src/app/chat/error.tsx`)
+
+2. **Loading States**
+   - Skeleton component (`src/components/ui/skeleton.tsx`)
+   - Loading spinner (`src/components/ui/spinner.tsx`)
+   - Chat loading skeleton (`src/app/chat/loading.tsx`)
+   - Dashboard loading skeleton (`src/app/dashboard/loading.tsx`)
+
+3. **Toast Notifications**
+   - Install shadcn Sonner component
+   - Add Toaster to layout
+
+4. **Chat UX Improvements**
+   - Message timestamps
+   - Copy-to-clipboard for AI responses
+   - Typing/thinking indicator during streaming
+   - Error display for API failures
+   - Message persistence (localStorage)
+
+5. **Database Indexes** - Add missing indexes on:
+   - `session.user_id`
+   - `session.token`
+   - `account.user_id`
+   - `account(provider_id, account_id)`
+   - `user.email`
+
+6. **Form Components**
+   - Input component (`src/components/ui/input.tsx`)
+   - Textarea component (`src/components/ui/textarea.tsx`)
+   - Label component (`src/components/ui/label.tsx`)
+
+### 3. Polish & Security (Medium Priority)
+
+1. **ESLint Enhancement**
+   - Import ordering rules
+   - TypeScript-eslint rules
+   - React hooks exhaustive-deps
+   - no-console warnings
+
+2. **API Hardening**
+   - Rate limiting for chat endpoint
+   - Zod validation for incoming messages
+   - Restrict diagnostics endpoint to admins
+
+3. **SEO Improvements**
+   - Per-page metadata
+   - Open Graph tags
+   - JSON-LD structured data
+   - Sitemap (`src/app/sitemap.ts`)
+   - Robots (`src/app/robots.ts`)
+
+4. **Accessibility**
+   - aria-label on interactive elements
+   - nav role in site header
+   - Proper form labels
+   - Skip-to-content link
+
+5. **TypeScript Strictness**
+   - `noUncheckedIndexedAccess: true`
+   - `noImplicitOverride: true`
+   - `exactOptionalPropertyTypes: true`
+
+### 4. Developer Experience (DevEx)
+
+1. **Prettier Configuration** - Add `.prettierrc` for consistent code formatting
+
+2. **CI/CD Pipeline** - GitHub Actions workflow with:
+   - Lint check
+   - Type check
+   - Build verification
+
+3. **Node Version Pinning** - Add `.nvmrc` for Node 20 LTS
+
+4. **CLI Scripts** - Add helpful package.json scripts:
+   - `validate-env` - Check required environment variables
+   - `check` - Run lint + typecheck in one command
+
+5. **Setup Experience** - Interactive setup script (`scripts/setup.ts`)
+
+6. **File Storage Security**
+   - File type whitelist
+   - File size limits
+   - Filename sanitization
+
+7. **Profile Page** - Enable disabled quick action buttons
+
+## Out of Scope
+
+- Unit testing framework
+- E2E testing framework
+- Dockerfile / container deployment
+- Database seeding