Today, before the article, let me introduce our new site — currently in beta:
🚀 Free TypeScript & AI Engineering Masterclass
This article is part of a structured roadmap designed to take you from TypeScript foundations to building production-ready AI applications. I have made the entire series available on a dedicated, lightning-fast platform:
👉 Access the TypeScript & AI Series on Programming Central
Why learn here?
- Zero Friction: No signup, no email required, and no "waitlists." Everything is instantly accessible for free.
- Structured Learning: Use the sidebar menu on the left to browse the full curriculum. Chapters flow logically from core concepts to real-world AI implementation.
- Engineering First: We don't just show syntax; we dive into practical examples and identify common pitfalls that senior developers avoid.
- Interactive Quizzes: At the end of each chapter, you can test your knowledge with our custom quiz engine.
How the quizzes work:
The system generates a random set of engineering challenges for every attempt. You get instant feedback and, most importantly, a detailed architectural explanation for every correct and incorrect choice. It’s designed to ensure you master the logic of AI engineering, not just the code.
Let me know what you think in the comments below.
Below you will find today's article.
Ever built a chat interface that feels lightning-fast in the browser, only to realize the conversation vanishes the moment the user refreshes the page? You’re not alone. This is the "Dual-State Problem"—the fundamental challenge of keeping a user's ephemeral UI experience in sync with a persistent server-side database.
In this chapter, we’ll dissect the architecture required to build robust, production-ready conversational interfaces using Next.js, React Server Components, and the Vercel AI SDK. We’ll move beyond simple "hello world" examples and explore how to manage complex state, handle streaming responses, and ensure data integrity without sacrificing performance.
The Core Concept: The Dual-State Problem in Conversational Interfaces
At the heart of any generative chat application lies a fundamental duality: the conversation exists simultaneously in two places.
- The Ephemeral Present (Client-Side State): This is the live feed on the user's screen. It’s volatile, high-frequency, and optimized for speed. When a user sends a message, they expect an immediate response. The UI must update instantly to show the user's message and a placeholder for the AI's response, which streams in token by token. In Next.js, this is typically managed by React's
useStateor the Vercel AI SDK'suseChathook. - The Persistent Past (Server-Side State): This is the authoritative record stored in your database (e.g., Vercel Postgres). It’s durable, reliable, and optimized for long-term storage. This state allows users to reload pages, switch devices, and provides the context for future AI interactions.
The challenge is that these two states are not automatically synchronized. The client-side state is a "view" of the data, not the source of truth. The server-side state is the source of truth, but it isn't immediately accessible for rendering. The architecture we build must act as a bridge, ensuring the ephemeral and the persistent remain in perfect harmony.
The Analogy: The Live Broadcast and the Archive
Imagine a live television broadcast of a breaking news event.
- Client-Side State is the live feed you see on your screen. It's immediate, fluid, and constantly updating. This is analogous to the
messagesarray in your React component, updated by theuseChathook as tokens stream in. - Server-Side State is the broadcast archive stored in the network's master server. It's the permanent record, indexed and available for anyone to watch later. This is analogous to the
chat_historytable in your database.
The role of the "producer" (our Next.js application) is to manage the live broadcast while simultaneously recording it to the archive. If the producer only focused on the live feed, the archive would be empty. If they only focused on the archive, the live feed would be delayed. We need a sophisticated architecture that captures every moment of the live feed and writes it to the archive in real-time, without causing noticeable lag.
The Architectural Pattern: Server Actions as the Synchronization Bridge
In the modern Next.js stack, the bridge between the client and the server is built with React Server Components (RSC) and Server Actions. This allows us to define server-side logic that can be called directly from client-side components as if they were local functions.
Let’s connect this to the concept of Generative UI. In previous chapters, we saw how a Server Component could stream a response directly from an AI model to the client. Now, we are extending that concept to handle client-to-server state push.
When a user types a message and hits "Send," the useChat hook invokes a Server Action. This Server Action performs two critical functions in a single, atomic operation:
- Persistence: It takes the user's message and writes it to the database. It then awaits the AI's response and writes each chunk (or the final message) to the database as well.
- Response Generation: It uses the Vercel AI SDK's
streamTextfunction to generate the AI's response, which is then streamed back to the client.
The beauty of this pattern is that the client doesn't need to know about the database. It simply calls the Server Action and receives a stream of data. The complex logic of database writes is encapsulated entirely on the server.
Under the Hood: The State Management Flow
Let's dissect the lifecycle of a single message in this architecture:
- User Input: The user types a message and presses "Enter." The
useChathook'shandleSubmitfunction is triggered. - Client-Side Optimistic Update: Before sending the request,
useChatimmediately updates its internalmessagesarray. This provides instant visual feedback—an optimistic update. - Server Action Invocation: The
useChathook calls the Server Action, passing the new message. - Server-Side Processing:
- Persistence: It first writes the user's message to the
chat_historytable. - Generation: It calls
streamTextfrom the Vercel AI SDK. - Streaming & Persistence: As tokens generate, the Server Action writes them to the database (buffering to avoid excessive writes) and streams them back to the client.
- Persistence: It first writes the user's message to the
- Client-Side Streaming: The
useChathook receives the streamed tokens and updates the UI progressively. - Completion: The Server Action ensures the final AI response is written to the database.
Basic Code Example: Persisting Chat History with Server Actions
This example demonstrates a minimal, self-contained chat application. It uses a Next.js Server Action to handle AI generation and persist the conversation to a database (simulated here with an in-memory store).
The Architecture
- Client Component (
ChatComponent.tsx): UsesuseChatto manage input and display messages. - Server Action (
sendMessage): Receives the user message, streams the AI response, and persists history. - Data Store: A simplified abstraction layer representing the database.
1. The Client Component
// app/components/ChatComponent.tsx
'use client';
import { useChat } from 'ai/react';
export default function ChatComponent({ initialMessages }: { initialMessages?: any[] }) {
// useChat hook manages the local UI state (messages, input value, loading status)
const { messages, input, handleInputChange, handleSubmit, isLoading, error } = useChat({
api: '/api/chat', // Points to our API route handler
initialMessages,
onFinish: (message) => {
console.log('Stream finished:', message);
}
});
return (
<div className="flex flex-col w-full max-w-md mx-auto p-4 border rounded-lg shadow-sm">
<div className="flex flex-col gap-4 mb-4 h-96 overflow-y-auto">
{messages.map((msg) => (
<div
key={msg.id}
className={`p-3 rounded-lg ${
msg.role === 'user'
? 'bg-blue-100 self-end text-blue-900'
: 'bg-gray-100 self-start text-gray-900'
}`}
>
<p className="text-sm font-semibold">{msg.role === 'user' ? 'You' : 'AI'}</p>
<p className="mt-1">{msg.content}</p>
</div>
))}
{isLoading && (
<div className="text-gray-500 text-sm animate-pulse">AI is thinking...</div>
)}
{error && (
<div className="text-red-500 text-sm">Error: {error.message}</div>
)}
</div>
<form onSubmit={handleSubmit} className="flex gap-2">
<input
type="text"
value={input}
onChange={handleInputChange}
placeholder="Type a message..."
className="flex-1 p-2 border rounded-md focus:outline-none focus:ring-2 focus:ring-blue-500"
disabled={isLoading}
/>
<button
type="submit"
disabled={isLoading}
className="px-4 py-2 bg-blue-600 text-white rounded-md hover:bg-blue-700 disabled:opacity-50"
>
Send
</button>
</form>
</div>
);
}
2. The Server Action (Backend Logic)
This file contains the server-side logic. It uses streamText and a simplified database mock.
// app/actions/chatActions.ts
'use server';
import { streamText } from 'ai';
import { openai } from '@ai-sdk/openai';
import { createStreamableValue } from 'ai/rsc';
// MOCK DATABASE: In a real app, use Vercel Postgres.
const mockDb = new Map<string, any[]>();
export async function sendMessage(history: any[], newMessage: string) {
// 1. Append user message to the history
const currentHistory = [...history, { role: 'user', content: newMessage }];
// 2. Generate a unique Session ID
const sessionId = 'session-123';
// 3. Persist the User Message immediately
mockDb.set(sessionId, currentHistory);
// 4. Prepare the AI Stream
const stream = createStreamableValue();
// 5. Run the AI generation asynchronously
(async () => {
try {
const result = await streamText({
model: openai('gpt-3.5-turbo'),
messages: currentHistory,
system: 'You are a helpful assistant.',
});
// 6. Stream the AI response to the client
for await (const chunk of result.textStream) {
stream.update(chunk);
}
stream.done();
// 7. Persist the AI response to the database
const finalAiMessage = { role: 'assistant', content: result.text };
const finalHistory = [...currentHistory, finalAiMessage];
mockDb.set(sessionId, finalHistory);
console.log(`Session ${sessionId} saved.`);
} catch (err) {
stream.error(err);
}
})();
return { stream: stream.value, sessionId };
}
3. The API Route (Connecting Client to Server Action)
Since useChat expects an API endpoint, we create a simple route handler.
// app/api/chat/route.ts
import { sendMessage } from '@/app/actions/chatActions';
import { NextRequest } from 'next/server';
export async function POST(req: NextRequest) {
const { messages } = await req.json();
// Extract the latest user message and history
const latestMessage = messages[messages.length - 1].content;
const history = messages.slice(0, -1);
// Call the Server Action
const { stream } = await sendMessage(history, latestMessage);
// Convert the RSC stream to a standard Web Response
return new Response(stream, {
headers: {
'Content-Type': 'text/plain; charset=utf-8',
},
});
}
Line-by-Line Explanation
-
'use client'vs'use server': These directives are crucial.'use client'marks components that run in the browser, allowing React hooks.'use server'marks functions that run on the server, ensuring secure access to databases and API keys. -
useChatHook: This abstracts away the complexity of managinguseStatefor messages, handling input changes, and streaming data. It automatically handles optimistic updates, making the UI feel instant. -
createStreamableValue: Provided by the Vercel AI SDK, this allows the server to send incremental updates to the client without waiting for the entire generation to finish. -
for await (const chunk of result.textStream): This is the magic of streaming. As the LLM generates tokens, we iterate through them and push them to the client immediately.
Common Pitfalls
- The "Stale Closure" Trap: If you define a Server Action inside a client component, it captures the state at the moment of definition. Always define Server Actions in separate files with the
'use server'directive and pass current state as arguments. - Vercel/Serverless Timeouts: LLM generation can be slow. If the stream takes longer than the platform's timeout (e.g., 10s on Vercel Hobby), the connection drops. Ensure you are using
streamTextwhich returns a stream immediately, rather than awaiting the full text generation. - Database Write Bottlenecks: Writing to the database synchronously inside the stream loop can slow down token delivery. Persist the User message before generation starts, and persist the AI message after the stream finishes using the accumulated
result.text. - Missing Directives: Double-check the top of every file. Components using hooks need
'use client'. Functions handling data logic need'use server'.
Advanced Application: Persistent Chat with Optimistic Branching
In a SaaS environment, conversations aren't always linear. Users often want to fork a conversation from a specific message to explore a different angle. This creates a tree-like structure.
To support branching, your database schema must move beyond a simple linear list. Instead of just a message table with a session_id, you might include parent_message_id or branch_id.
When a user asks a follow-up question, the Server Action must be smart enough to provide the AI with the correct branch of the conversation. It can't just grab the last 10 messages. It needs to traverse the conversation tree to find the relevant context.
The useChat hook's messages array is particularly clever here. On the client, it represents the current branch the user is viewing. When this array is sent to the server, it provides the exact context needed for the AI to generate a coherent response, effectively "teleporting" the AI to that specific point in the conversation history.
Why This Architecture is Essential
- State Resilience: If the user's browser crashes, the conversation is safe in the database.
- Multi-Device Synchronization: A user can start on a laptop and continue on a phone because the state is server-authoritative.
- Performance: Offloading database writes to the server keeps the client lightweight.
- Advanced Features: This architecture enables conversation sharing, history search, and data analysis—features impossible if state only exists in client-side variables.
Conclusion
Managing chat history in Next.js is not about choosing between client-side or server-side state. It's about architecting a robust, real-time synchronization system between the two.
By leveraging Server Actions as a synchronization bridge, you can decouple the heavy lifting (AI generation and database writes) from the client, resulting in a lightweight, reactive, and persistent user experience. Whether you are building a simple Q&A bot or a complex multi-branching SaaS application, this pattern provides the foundation for a seamless, intelligent conversational interface.
The concepts and code demonstrated here are drawn directly from the comprehensive roadmap laid out in the book The Modern Stack. Building Generative UI with Next.js, Vercel AI SDK, and React Server Components Link
Take a look at my eBooks
- Python
- JavaScript & TypeScript
- C# / .NET
- Swift & Apple Platform
- Kotlin & Android
- Rust
JavaScript & TypeScript
Foundations
OpenAI API, Zod, and LangChain.js
The Modern Stack
Building Generative UI with Next.js, Vercel AI SDK, and React Server Components.
Master Your Data
Production RAG, Vector Databases, and Enterprise Search.
Autonomous Agents
Building Multi-Agent Systems and Workflows with LangGraph.js
The Edge of AI
Local LLMs (Ollama), Transformers.js, WebGPU, and Performance Optimization
The AI-Ready SaaS Boilerplate. Auth, Database with Vector Support, and Payment Stack
Auth, Database with Vector Support, and Payment Stack.
Backend for Frontend & Intelligent APIs. tRPC, Edge Functions, and LLM Data Transformation
tRPC, Edge Functions, and LLM Data Transformation.
The Monetization Engine. Stripe, Smart Dunning, and AI Customer Support Agents
Stripe, Smart Dunning, and AI Customer Support Agents.
AI-Driven Growth Engineering. Programmatic SEO with GPT-4, Content Automation, and Analytics.
Programmatic SEO with GPT-4, Content Automation, and Analytics.
No More Localhost. Mastering Docker, Linux, and Containerization for JS & AI Apps
Mastering Docker, Linux, and Containerization for JS & AI Apps.
The Perfect Pipeline. Advanced CI/CD with GitHub Actions, Automated Testing, and AI Code Reviews
Advanced CI/CD with GitHub Actions, Automated Testing, and AI Code Reviews.
Kubernetes & Orchestration. Deploying Scalable Node.js & AI Clusters without Tears
Deploying Scalable Node.js & AI Clusters without Tears.
React Native for Web Developers
From Next.js to Expo, NativeWind, and Universal App
Offline AI & Local LLMs. Running Llama 3 and Vector Search directly on the Smartphone
Running Llama 3 and Vector Search directly on the Smartphone.
App Store Engineering. CI/CD for Mobile (EAS), OTA Updates, and AI-Driven App Store Optimization
CI/CD for Mobile (EAS), OTA Updates, and AI-Driven App Store Optimization.
The TypeScript-First Architect. Building Robust Applications with Effect, Zod, and Drizzle
Building Robust Applications with Effect, Zod, and Drizzle.
The Native Era. Modern Node.js, Bun & Deno without Bundlers or Transpilers
Modern Node.js, Bun & Deno without Bundlers or Transpilers.
Local-First Systems in TypeScript. Collaborative & Offline-Ready Web Apps with CRDTs and WASM DBs
Collaborative & Offline-Ready Web Apps with CRDTs and WASM DBs.
TypeScript Metaprogramming. Advanced Type Gymnastics, Modern Decorators, and Compiler Internals
Advanced Type Gymnastics, Modern Decorators, and Compiler Internals.
Standardizing Tool Integration, Vision-Driven Browser Automation, and Agent Governance in TypeScript.
Generative Media & Visual Workflow Engines. Node-Based AI Canvases, Real-Time Media Streaming Pipelines, and WebGPU Processing in TypeScript
Node-Based AI Canvases, Real-Time Media Streaming Pipelines, and WebGPU Processing in TypeScript.
Neuro-Symbolic AI & Knowledge Graphs. Deterministic Solvers, GraphDBs, Ontologies, and Zero-Hallucination Architectures
Deterministic Solvers, GraphDBs, Ontologies, and Zero-Hallucination Architectures in TypeScript.
Event-Driven Architecture & DDD in TypeScript. Event Sourcing, CQRS, and Microservices at Scale
Event Sourcing, CQRS, and Microservices at Scale.
Building Desktop Apps & Developer Tools with Tauri 2.0, Rust, and TypeScript
Cross-platform desktop tools with Tauri, Rust, and TypeScript.
FinTech Architecture in TypeScript. Precision Math, Double-Entry Ledgers, and High-Reliability Payment Pipelines
Precision Math, Double-Entry Ledgers, and High-Reliability Payment Pipelines.
Hardened TypeScript. Passkeys, Supply Chain Defense, and Zero-Trust Architectures
Passkeys, Supply Chain Defense, and Zero-Trust Architectures.
Spatial Web Development. Building Interactive 3D and WebXR Experiences with React Three Fiber & TypeScript
Building Interactive 3D and WebXR Experiences with React Three Fiber & TypeScript.
Multiple-choice test book for: Foundations (Volume 1)
Spatial Web Development. Building Interactive 3D and WebXR Experiences with React Three Fiber & TypeScript
Building Interactive 3D and WebXR Experiences with React Three Fiber & TypeScript.
Jev: The Definitive Guide to System One AI
Building Sub-100ms Decision Engines, Calibrated Guardrails, and Two-Speed Architectures with Jev and Generative LLMs
Python
Data Structures and the Standard Library
Web Development with Python
Building backend services and dynamic websites with a framework like Flask
Advanced Python & AI Integration
Deep dive into OOP, decorators, asyncio, and orchestrating LLMs with LangChain.
Gemini 3 Python Programming - The Complete Guide
Agents, Veo 3.1, Lyria, Nano Banana/Pro, Function Calling, Grounding, Computer Use and Robotics
AI Autonomous Agents with Python Programming
Master LangGraph, CrewAI, and RAG to Build Self-Correcting Swarms and Autonomous Digital Workers
Finance & AI Trading with Python Programming
Master Algorithmic Trading, Financial NLP, and Vectorized Backtesting to Build Autonomous 'News + Math' Strategies
Cloud-Native Python, DevOps & LLMOps. Containerization, Kubernetes, and Serving AI Models at Scale
From Docker and Kubernetes to Serving LLMs with Pulumi
Defensive Cybersecurity with Python Programming
A Practical Guide to System Monitoring, Network Defense, and Automated Security Hardening
Data Science & Analytics with Python Programming
Neural Networks & Deep Learning with Python Programming
Architecting Neuro-Symbolic Agents with Python Programming
Integrating LLMs, Wolfram Alpha, IBM Watson and Open Source Stacks for Near-Zero Hallucination Systems
Bioinformatics & AI with Python Programming
Master Genomic Data Science, Protein Folding with AlphaFold, and AI-Driven Drug Discovery
Geospatial AI (GeoAI) with Python Programming
Building Autonomous GIS Agents, Deep Learning Models, and Interactive Dashboards
Astrophysics & AI with Python Programming
Building Research Agents for Astronomy, Cosmology, and SETI
Open-Source LLMs & Local Fine-Tuning
Mastering LoRA, vLLM, Ollama, and Custom SLMs
Unsloth: Efficient Fine-Tuning for Large Language Models
Methods and Workflows for Fine-Tuning and Deploying Large Language Models on Limited Hardware
Hermes Agent: The Self-Evolving AI Workforce
Architecting Autonomous Systems that Learn, Remember, and Grow.
Frontier AI Safety, Mechanistic Interpretability & Alignment Engineering
Inspecting Neural Circuits, Steering Vectors, Autonomous Capability Evals, and Scalable Oversight for Superintelligent Systems.
C# / .NET
Get all the Ten C# & AI volumes at a discounted price, or choose an ebook:
The Foundations
Syntax, Type System, and Logic for Modern Developers.
Advanced OOP & AI Data Structures
Modeling Complex Systems and Tensors.
Data Manipulation, LINQ & Vectors
From Collections to AI Embeddings
Asynchronous AI Pipelines
Async/Await, Parallelism, and Streaming LLM Responses.
Building AI Web APIs with ASP
NET Core. Serving Models and Chat Endpoints
Intelligent Data Access with EF Core
Vector Databases, RAG, and Memory Storage.
Cloud-Native AI & Microservices
Containerizing Agents and Scaling Inference.
The Core of AI Engineering: Microsoft Semantic Kernel & Agentic Patterns
Edge AI & Local Inference
Running LLMs (Llama/Phi) locally with C# and ONNX.
High-Performance C# for AI
Span, SIMD, and Optimizing Token Processing
Full Stack AI with Blazor. Building Interactive Copilots and WASM AI
Building Interactive Copilots and WASM AI.
Enterprise AI Integration & Process Automation. Connecting LLMs to legacy systems, internal APIs, and real-world business processes
Connecting LLMs to legacy systems, internal APIs, and real-world business processes.
AI for Game Development & Interactive Simulation. Using LLMs and generative AI to create dynamic worlds and intelligent characters in Unity
Using LLMs and generative AI to create dynamic worlds and intelligent characters in Unity.
Swift & Apple Platform
Core ML & Vision Framework
On-device image classification, object detection, and custom model integration with Core ML and Vision.
Apple Intelligence & Foundation Models
Building apps with Apple's on-device LLM APIs, Writing Tools, and the Apple Intelligence framework
Natural Language & Speech
NLP, sentiment analysis, text classification, and Speech-to-Text with Apple's Natural Language and Speech frameworks.
SwiftUI for AI Apps
Building reactive, intelligent interfaces that respond to model outputs, stream tokens, and visualize AI predictions in real time
Create ML Studio
Training custom models without Python: tabular, image, sound, and motion classifiers using Create ML in Swift.
MLX Swift & Local LLMs. Deep dive into Apple's MLX framework for high-performance machine learning.
Building custom inference engines, fine-tuning local models (LoRA), and leveraging Unified Memory directly from Swift.
visionOS & Spatial AI with Swift
Swift + OpenAI & LangChain
Integrating external LLM APIs, RAG pipelines, and agentic workflows in iOS and macOS apps
CoreData, CloudKit & Vector Search
Shipping AI Apps to the App Store
Kotlin & Android
On-Device GenAI with Android Kotlin
Mastering Gemini Nano, AICore, and local LLM deployment using MediaPipe and Custom TFLite models
Edge AI Performance with Android Kotlin
Optimizing hardware acceleration via NPU, GPU, and DSP. Advanced quantization and model pruning
Android AI Agents
Building autonomous apps that use Tool Calling, Function Injection, and Screen Awareness to perform tasks for the user
Rust
Rust Advanced Memory Patterns for AI
Mastering Lifetimes, Smart Pointers, and custom allocators for managing large models and datasets
Extending Python with Rust. Creating high-performance Python modules with PyO3.
Creating high-performance Python modules with PyO3 for data processing, tokenization, and inference, replacing slow Python code.
Top comments (0)