agentic-coding-starter-kit/specs/boilerplate-improvements/implementation-plan.md

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 - Keep public (used by homepage setup checklist before login)

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