Next.js integration: SDK, examples, and developer success guide

[jhs]

Overview

Provide comprehensive Next.js support for Chatfield with reference implementations, SDK patterns, and developer success documentation.

Primary Goal

Make Next.js developers highly successful with Chatfield through clear patterns, examples, and best practices.

Secondary Goal

Demonstrate production-ready LiteLLM proxy integration for secure API key handling.

Deliverables

1. Next.js Reference Implementation

Stack:

• Next.js 14+ (App Router + Pages Router examples)
• @chatfield/react hooks
• LiteLLM proxy for API key security
• TypeScript throughout

Features to demonstrate:

• Server Components for interview definition
• Client Components for conversation UI
• API routes for proxy communication
• Environment variable configuration
• Error boundaries and loading states
• Production deployment considerations

2. LiteLLM Proxy Integration

Setup:

• Docker Compose configuration (PostgreSQL + LiteLLM)
• Next.js API route that proxies to LiteLLM
• Secure token management
• Rate limiting and usage tracking
• Development vs production configurations

Security model:

• No API keys in browser code
• Server-side proxy handles authentication
• Audit trail in PostgreSQL
• Read-only virtual keys for development

3. Developer Success Documentation

Getting Started Guide:

# Chatfield + Next.js Quick Start

## Installation
npm install @chatfield/core @chatfield/react

## 1. Define Interview (Server Component or shared)
// app/interviews/contact.ts
export const contactInterview = chatfield()
  .field('name', 'Your name')
  .field('email', 'Email address')
  .build()

## 2. Create Conversation UI (Client Component)
// app/components/ContactForm.tsx
'use client'
export function ContactForm() {
  const [state, actions] = useChatfield(contactInterview)
  // ... UI implementation
}

## 3. Configure Proxy
// .env.local
NEXT_PUBLIC_LITELLM_PROXY=http://localhost:4000
OPENAI_API_KEY=sk-...

## 4. Run Development Server
npm run dev

Advanced Topics:

• Streaming responses (future)
• Multi-step interviews across pages
• Server Actions integration
• Edge runtime compatibility
• Vercel deployment
• Self-hosted deployment

4. Example Applications

Example 1: Contact Form (Simple)

• Single page app
• Basic interview with 3-4 fields
• Shows minimal setup

Example 2: Job Application (Complex)

• Multi-page flow
• Conditional fields
• File uploads (future)
• Progress persistence

Example 3: Customer Onboarding (Production-Ready)

• Full authentication
• Database integration
• Email notifications
• Analytics tracking

5. SDK Patterns

Recommended Architecture:

next-app/
├── app/
│   ├── api/
│   │   └── chat/route.ts          # Proxy endpoint
│   ├── interviews/
│   │   ├── contact.ts              # Interview definitions
│   │   └── onboarding.ts
│   └── components/
│       └── ChatfieldConversation.tsx
├── lib/
│   ├── chatfield-client.ts        # Client-side utilities
│   └── chatfield-server.ts        # Server-side utilities
└── docker-compose.yml              # LiteLLM stack

Key Patterns:

• Interview definitions as shared modules
• Client/server boundary best practices
• Proxy configuration patterns
• State management (URL params, cookies, database)
• Error handling and retry logic

Implementation Plan

Phase 1: Basic Next.js Support

• Create examples/nextjs-basic/ with minimal app
• App Router example with useChatfield
• Pages Router example (for comparison)
• Basic README with setup instructions

Phase 2: LiteLLM Integration

• Docker Compose setup for LiteLLM proxy
• Next.js API route for proxying
• Environment configuration guide
• Security documentation

Phase 3: Comprehensive Documentation

• Getting Started guide in Documentation/Next.js.md
• Architecture patterns document
• Deployment guide (Vercel, self-hosted)
• Troubleshooting guide

Phase 4: Advanced Examples

• Multi-page interview flow example
• Production-ready template with auth
• Server Actions integration example

Phase 5: Developer Success

• Video walkthrough (optional)
• Blog post or tutorial
• Community templates repository
• Stack Overflow / Discord support patterns

Success Metrics

• Next.js developer can go from zero to working Chatfield app in < 15 minutes
• Clear production deployment path
• No security footguns (API keys in client code, etc.)
• Works with latest Next.js stable version

Out of Scope

• ❌ Create React App (deprecated)
• ❌ Remix (separate issue if requested)
• ❌ Gatsby (separate issue if requested)
• ❌ Vue/Nuxt (different framework)

Dependencies

• Requires Create @chatfield/react package for React integrations #50 (@chatfield/react package) to be completed first
• Builds on TypeScript Build System: Browser support, npm packaging, and LiteLLM proxy #48 (browser build system + LiteLLM proxy)

References

• Next.js docs: https://nextjs.org/docs
• LiteLLM: https://docs.litellm.ai/
• Vercel deployment: https://vercel.com/docs