1# Data Patterns
2 
3Choose the right data fetching pattern for each use case.
4 
5## Decision Tree
6 
7```
8Need to fetch data?
9├── From a Server Component?
10│   └── Use: Fetch directly (no API needed)
11│
12├── From a Client Component?
13│   ├── Is it a mutation (POST/PUT/DELETE)?
14│   │   └── Use: Server Action
15│   └── Is it a read (GET)?
16│       └── Use: Route Handler OR pass from Server Component
17│
18├── Need external API access (webhooks, third parties)?
19│   └── Use: Route Handler
20│
21└── Need REST API for mobile app / external clients?
22    └── Use: Route Handler
23```
24 
25## Pattern 1: Server Components (Preferred for Reads)
26 
27Fetch data directly in Server Components - no API layer needed.
28 
29```tsx
30// app/users/page.tsx
31async function UsersPage() {
32  // Direct database access - no API round-trip
33  const users = await db.user.findMany();
34 
35  // Or fetch from external API
36  const posts = await fetch('https://api.example.com/posts').then(r => r.json());
37 
38  return (
39    <ul>
40      {users.map(user => <li key={user.id}>{user.name}</li>)}
41    </ul>
42  );
43}
44```
45 
46**Benefits**:
47- No API to maintain
48- No client-server waterfall
49- Secrets stay on server
50- Direct database access
51 
52## Pattern 2: Server Actions (Preferred for Mutations)
53 
54Server Actions are the recommended way to handle mutations.
55 
56```tsx
57// app/actions.ts
58'use server';
59 
60import { revalidatePath } from 'next/cache';
61 
62export async function createPost(formData: FormData) {
63  const title = formData.get('title') as string;
64 
65  await db.post.create({ data: { title } });
66 
67  revalidatePath('/posts');
68}
69 
70export async function deletePost(id: string) {
71  await db.post.delete({ where: { id } });
72 
73  revalidateTag('posts');
74}
75```
76 
77```tsx
78// app/posts/new/page.tsx
79import { createPost } from '@/app/actions';
80 
81export default function NewPost() {
82  return (
83    <form action={createPost}>
84      <input name="title" required />
85      <button type="submit">Create</button>
86    </form>
87  );
88}
89```
90 
91**Benefits**:
92- End-to-end type safety
93- Progressive enhancement (works without JS)
94- Automatic request handling
95- Integrated with React transitions
96 
97**Constraints**:
98- POST only (no GET caching semantics)
99- Internal use only (no external access)
100- Cannot return non-serializable data
101 
102## Pattern 3: Route Handlers (APIs)
103 
104Use Route Handlers when you need a REST API.
105 
106```tsx
107// app/api/posts/route.ts
108import { NextRequest, NextResponse } from 'next/server';
109 
110// GET is cacheable
111export async function GET(request: NextRequest) {
112  const posts = await db.post.findMany();
113  return NextResponse.json(posts);
114}
115 
116// POST for mutations
117export async function POST(request: NextRequest) {
118  const body = await request.json();
119  const post = await db.post.create({ data: body });
120  return NextResponse.json(post, { status: 201 });
121}
122```
123 
124**When to use**:
125- External API access (mobile apps, third parties)
126- Webhooks from external services
127- GET endpoints that need HTTP caching
128- OpenAPI/Swagger documentation needed
129 
130**When NOT to use**:
131- Internal data fetching (use Server Components)
132- Mutations from your UI (use Server Actions)
133 
134## Avoiding Data Waterfalls
135 
136### Problem: Sequential Fetches
137 
138```tsx
139// Bad: Sequential waterfalls
140async function Dashboard() {
141  const user = await getUser();        // Wait...
142  const posts = await getPosts();      // Then wait...
143  const comments = await getComments(); // Then wait...
144 
145  return <div>...</div>;
146}
147```
148 
149### Solution 1: Parallel Fetching with Promise.all
150 
151```tsx
152// Good: Parallel fetching
153async function Dashboard() {
154  const [user, posts, comments] = await Promise.all([
155    getUser(),
156    getPosts(),
157    getComments(),
158  ]);
159 
160  return <div>...</div>;
161}
162```
163 
164### Solution 2: Streaming with Suspense
165 
166```tsx
167// Good: Show content progressively
168import { Suspense } from 'react';
169 
170async function Dashboard() {
171  return (
172    <div>
173      <Suspense fallback={<UserSkeleton />}>
174        <UserSection />
175      </Suspense>
176      <Suspense fallback={<PostsSkeleton />}>
177        <PostsSection />
178      </Suspense>
179    </div>
180  );
181}
182 
183async function UserSection() {
184  const user = await getUser(); // Fetches independently
185  return <div>{user.name}</div>;
186}
187 
188async function PostsSection() {
189  const posts = await getPosts(); // Fetches independently
190  return <PostList posts={posts} />;
191}
192```
193 
194### Solution 3: Preload Pattern
195 
196```tsx
197// lib/data.ts
198import { cache } from 'react';
199 
200export const getUser = cache(async (id: string) => {
201  return db.user.findUnique({ where: { id } });
202});
203 
204export const preloadUser = (id: string) => {
205  void getUser(id); // Fire and forget
206};
207```
208 
209```tsx
210// app/user/[id]/page.tsx
211import { getUser, preloadUser } from '@/lib/data';
212 
213export default async function UserPage({ params }) {
214  const { id } = await params;
215 
216  // Start fetching early
217  preloadUser(id);
218 
219  // Do other work...
220 
221  // Data likely ready by now
222  const user = await getUser(id);
223  return <div>{user.name}</div>;
224}
225```
226 
227## Client Component Data Fetching
228 
229When Client Components need data:
230 
231### Option 1: Pass from Server Component (Preferred)
232 
233```tsx
234// Server Component
235async function Page() {
236  const data = await fetchData();
237  return <ClientComponent initialData={data} />;
238}
239 
240// Client Component
241'use client';
242function ClientComponent({ initialData }) {
243  const [data, setData] = useState(initialData);
244  // ...
245}
246```
247 
248### Option 2: Fetch on Mount (When Necessary)
249 
250```tsx
251'use client';
252import { useEffect, useState } from 'react';
253 
254function ClientComponent() {
255  const [data, setData] = useState(null);
256 
257  useEffect(() => {
258    fetch('/api/data')
259      .then(r => r.json())
260      .then(setData);
261  }, []);
262 
263  if (!data) return <Loading />;
264  return <div>{data.value}</div>;
265}
266```
267 
268### Option 3: Server Action for Reads (Works But Not Ideal)
269 
270Server Actions can be called from Client Components for reads, but this is not their intended purpose:
271 
272```tsx
273'use client';
274import { getData } from './actions';
275import { useEffect, useState } from 'react';
276 
277function ClientComponent() {
278  const [data, setData] = useState(null);
279 
280  useEffect(() => {
281    getData().then(setData);
282  }, []);
283 
284  return <div>{data?.value}</div>;
285}
286```
287 
288**Note**: Server Actions always use POST, so no HTTP caching. Prefer Route Handlers for cacheable reads.
289 
290## Quick Reference
291 
292| Pattern | Use Case | HTTP Method | Caching |
293|---------|----------|-------------|---------|
294| Server Component fetch | Internal reads | Any | Full Next.js caching |
295| Server Action | Mutations, form submissions | POST only | No |
296| Route Handler | External APIs, webhooks | Any | GET can be cached |
297| Client fetch to API | Client-side reads | Any | HTTP cache headers |
298