ros/agentic-coding-starter-kit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
a3a151c67a404fd88c289d6e9dd308fca0d102b8
agentic-coding-starter-kit/specs/boilerplate-improvements/requirements.md
Leon van Zyl a3a151c67a 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

4.2 KiB
Raw Blame History

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