The Next.js Mistakes AI Builders Keep Making

1
// Server Component
2
export default async function Page() {
3
  const posts = await getPosts();
4
  return <PostFilter posts={posts} />; // PostFilter is 'use client'
5
}

1
// Server Component
2
import { Suspense } from 'react';
3

4
export default function Page() {
5
  const posts = getPosts(); // no await
6

7
  return (
8
    <Suspense fallback={<Skeleton />}>
9
      <PostList postsPromise={posts} />
10
    </Suspense>
11
  );
12
}

1
// These do NOT run in parallel when each function is a Server Action
2
await Promise.all([askClaude(question), askGPT(question), askGemini(question)]);

1
// Parallel work inside ONE action
2
'use server';
3

4
export async function askAll(question: string) {
5
  const [claude, gpt, gemini] = await Promise.all([
6
    askClaude(question),
7
    askGPT(question),
8
    askGemini(question),
9
  ]);
10

11
  return { claude, gpt, gemini };
12
}

1
'use server';
2

3
import { revalidatePath } from 'next/cache';
4

5
export async function savePost(formData: FormData) {
6
  await savePostToDatabase(formData);
7
  revalidatePath('/posts');
8
  return { ok: true };
9
}

1
'use client';
2

3
import useSWR from 'swr';
4

5
const fetcher = (url: string) => fetch(url).then((r) => r.json());
6

7
export default function LiveScores() {
8
  const { data, error, isLoading } = useSWR('/api/live-scores', fetcher, {
9
    refreshInterval: 5000,
10
  });
11

12
  if (isLoading) return <p>Loading…</p>;
13
  if (error) return <p>Something went wrong.</p>;
14

15
  return <ScoreBoard scores={data} />;
16
}

1
'use server';
2

3
export async function deleteUser(userId: string) {
4
  await db.user.delete({ where: { id: userId } });
5
}

1
'use server';
2

3
import { auth } from '@/lib/auth';
4

5
export async function deleteUser(userId: string) {
6
  const session = await auth();
7
  if (!session?.user) throw new Error('Unauthorized');
8
  if (session.user.role !== 'admin') throw new Error('Forbidden');
9

10
  await db.user.delete({ where: { id: userId } });
11
}

1
'use server';
2

3
export async function updatePost(postId: string, content: string) {
4
  const session = await auth();
5
  if (!session?.user) throw new Error('Unauthorized');
6

7
  await db.post.update({ where: { id: postId }, data: { content } });
8
}

1
'use server';
2

3
export async function updatePost(postId: string, content: string) {
4
  const session = await auth();
5
  if (!session?.user) throw new Error('Unauthorized');
6

7
  const post = await db.post.findFirst({
8
    where: { id: postId, authorId: session.user.id },
9
  });
10
  if (!post) throw new Error('Not found');
11

12
  await db.post.update({ where: { id: post.id }, data: { content } });
13
}

1
const post = await db.post.findUnique({ where: { id } });
2

3
// ✅
4
const post = await db.post.findFirst({
5
  where: { id, authorId: session.user.id },
6
});

1
export default async function Page() {
2
  const user = await db.user.findUnique({ where: { id } });
3
  return <Profile user={user} />; // Profile is 'use client'
4
}

1
export default async function Page() {
2
  const user = await db.user.findUnique({
3
    where: { id },
4
    select: { id: true, name: true, avatarUrl: true },
5
  });
6

7
  return <Profile user={user} />;
8
}

1
catch (error) {
2
  return Response.json({ error: error.message }, { status: 500 });
3
}

1
catch (error) {
2
  console.error(error);
3
  return new Response('Internal error', { status: 500 });
4
}

1
import { auth } from '@/lib/auth';
2
import { checkRateLimit } from '@/lib/rate-limit';
3
import { schema } from './schema';
4

5
export async function POST(request: Request) {
6
  // 1. Authenticate — always. It's an open URL.
7
  const session = await auth();
8
  if (!session) return new Response(null, { status: 401 });
9

10
  // 2. Rate limit
11
  const { limited } = await checkRateLimit(request);
12
  if (limited) {
13
    return Response.json({ error: 'Too many requests' }, { status: 429 });
14
  }
15

16
  // 3. Validate the body — untrusted input
17
  const parsed = schema.safeParse(await request.json());
18
  if (!parsed.success) {
19
    return Response.json({ error: 'Bad request' }, { status: 400 });
20
  }
21

22
  try {
23
    // 4. Authorize the specific operation inside doWork,
24
    //    scoped to session.user.id — not just "is logged in"
25
    const result = await doWork(parsed.data, session.user.id);
26
    return Response.json(result);
27
  } catch (error) {
28
    // 5. Log the real error, return a safe one
29
    console.error(error);
30
    return new Response('Internal error', { status: 500 });
31
  }
32
}

1
# NextJS Coding Agent Guidelines
2

3
## This is NOT the Next.js you know
4

5
This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` (resolved from this file's directory; in monorepos the `next` package may not be visible from the repo root) before writing any code. Heed deprecation notices.
6

7
This block is written and re-added by `next dev` — verify at `node_modules/next/dist/server/lib/generate-agent-files.js`. Removing it from a diff only re-creates the uncommitted change; committing it with your work keeps the tree clean.
8

9
## Non-negotiable data rules
10

11
These apply to **every** piece of code that reads or writes data, regardless of whether it lives in a Server Component, a Server Action, or a Route Handler. Later sections assume these and do not repeat them.
12

13
1. **Authenticate and authorize at the point of data access.** A check on the page that renders a form does not protect the action the form calls. A check in `proxy.ts` does not protect the route. The check belongs next to the query.
14
2. **Scope every query by ownership, not just by ID.** An ID from a URL, a form field, or an action argument is attacker-controlled. Use `where: { id, ownerId: session.user.id }`, never `where: { id }` alone, for anything a user shouldn't see or edit universally.
15
3. **Derive identity from the session.** If a request supplies an `ownerId`, `userId`, `role`, `tenantId`, or price, ignore it and look it up server-side.
16
4. **Validation is not authorization.** Zod checks that input has the right _shape_. A perfectly valid `{ postId: "abc" }` can still point at someone else's row.
17
5. **Return and pass only the fields the UI renders.** Anything crossing into a Client Component — as props or as a Server Action return value — is serialized into the RSC payload and readable in page source. Use `select:` / explicit DTOs. Never pass a raw ORM record.
18
6. **Rate limit anything expensive.** LLM calls, email sends, image generation, auth attempts, file processing. This applies to Server Actions as much as Route Handlers.
19
7. **Never return internal errors to the client.** Log the real error server-side; return a generic message and status. ORM errors leak schema.
20
8. **Never cache session-dependent output.** See the caching section — this is the one mistake in this file that no auth check will catch.
21

22
## Client vs Server Components
23

24
- Everything is a Server Component by default. Do **not** put `"use server"` at the top of a regular server component — that directive is only for Server Functions.
25
- Push `"use client"` as **low as possible** in the tree. When you need interactivity, extract a small leaf client component rather than converting a whole subtree.
26
- The directive marks a **boundary**: anything imported below it is already in the client graph. Re-declaring `"use client"` in every descendant file is a team convention, not a framework requirement — do it for legibility if you like, but nothing breaks without it.
27
- Server Components can be passed as `children`/props into Client Components and remain server components. Client/server is determined by **imports**, not nesting.
28
- No React state or hooks (`useState`, `useEffect`, `useContext`, …) in Server Components.
29
- Client Components render on both server (SSR) and client (hydration) — their logs appear in both terminal and browser console.
30
- **Props crossing the boundary are public.** They are serialized into the RSC payload and visible in page source. Passing a whole user record leaks `passwordHash`, `stripeCustomerId`, and every other column even though the query ran on the server:
31

32
```tsx
33
// ❌ every column ships to the browser
34
const user = await db.user.findUnique({ where: { id } });
35
return <Profile user={user} />;
36

37
// ✅
38
const user = await db.user.findUnique({
39
  where: { id },
40
  select: { id: true, name: true, avatarUrl: true },
41
});
42
return <Profile user={user} />;
43
```
44

45
## Choosing where server code runs
46

47
Three tools, three jobs. Pick by **who calls it** and **whether it mutates**.
48

49
| Situation                                                                        | Use                                                       |
50
| -------------------------------------------------------------------------------- | --------------------------------------------------------- |
51
| Reading data to render a page                                                    | Call the data function directly in a **Server Component** |
52
| Mutation triggered by your own UI (form submit, button click)                    | **Server Action**                                         |
53
| Caller is not your React app (webhook, callback URL, mobile client, third party) | **Route Handler**                                         |
54
| Non-HTML content type (JSON API, XML, RSS, files, images)                        | **Route Handler**                                         |
55
| Proxying/aggregating an external or internal backend                             | **Route Handler**                                         |
56
| Client-side read that genuinely cannot be server-rendered                        | **Route Handler** + SWR / React Query                     |
57

58
## Reads: fetch in Server Components, directly from the source
59

60
- Fetch with `fetch`, an ORM, or a database client directly inside an async Server Component. Credentials and query logic never reach the client bundle.
61
- **Do NOT fetch from your own Route Handlers inside a Server Component.**
62
  - At build time (prerendered) this **fails the build** — no server is listening.
63
  - At request time it adds a needless HTTP round trip between the handler and the render process.
64
- **Authorize reads.** A read is not automatically safe because it doesn't mutate. `app/posts/[id]/page.tsx` receives whatever ID is in the URL:
65

66
```ts
67
// ❌ any logged-in user can read any post
68
const post = await db.post.findUnique({ where: { id } });
69

70
// ✅ scoped to the caller
71
const session = await auth();
72
if (!session?.user) redirect('/login');
73

74
const post = await db.post.findFirst({
75
  where: { id, authorId: session.user.id },
76
});
77
if (!post) notFound();
78
```
79

80
- Pass results down to Client Components as props — selected fields only (see above).
81
- To stream: do **not** await in the Server Component. Pass the promise as a prop and read it with React's `use()` inside a `<Suspense>` boundary.
82
- Wrap shared data-fetching functions in `React.cache` so multiple components in one request share a result instead of refetching. Scope is a single request only.
83
- Identical `fetch` calls in one React tree are memoized by default — fetch in the component that needs the data instead of prop-drilling.
84

85
## Mutations: Server Actions
86

87
Use a Server Action (`'use server'`) when **all** of these hold:
88

89
- It performs a mutation (create/update/delete) or a side effect (email, job dispatch).
90
- It is UI-specific, not a general-purpose public API.
91
- The caller is your own Next.js frontend.
92

93
Structural properties that drive the rule:
94

95
- Actions are **POST only** under the hood.
96
- **The client dispatches actions one at a time.** Three actions fired in quick succession queue behind each other. `Promise.all` does **not** parallelize them. This is the main reason they are wrong for reads.
97
- When an action revalidates, Next.js runs the action **and** re-renders the route in a single HTTP request. The response carries both the return value and a fresh RSC Payload. No follow-up fetch is needed to show the updated UI.
98

99
Do **not** create Server Actions whose purpose is a GET-only read. If you need parallel work, do it inside a single Server Action, or fetch in parallel from a Server Component, or use a Route Handler.
100

101
Shape of a correct action — auth, ownership-scoped lookup, mutation, revalidation:
102

103
```ts
104
'use server';
105

106
import { auth } from '@/lib/auth';
107
import { updateTag } from 'next/cache';
108

109
export async function updatePost(postId: string, content: string) {
110
  const session = await auth();
111
  if (!session?.user) throw new Error('Unauthorized');
112

113
  const post = await db.post.findFirst({
114
    where: { id: postId, authorId: session.user.id },
115
  });
116
  if (!post) throw new Error('Not found');
117

118
  await db.post.update({ where: { id: post.id }, data: { content } });
119
  updateTag(`post-${post.id}`);
120

121
  return { ok: true };
122
}
123
```
124

125
Calling them:
126

127
- From Server Components directly, or from `<form action={...}>` / `<button formAction={...}>`.
128
- From Client Components via `useActionState`, `useTransition`, or an event handler wrapped in `startTransition`.
129
- Server Functions cannot be _defined_ in Client Components — define them in a `'use server'` file and import.
130

131
Destructive operations (deletes, permission changes, payment actions) may warrant an elevated session check or re-authentication, and should fail loudly rather than silently no-op.
132

133
## Route Handlers
134

135
- Live in `app/api/.../route.ts`. They are **public HTTP endpoints** — anyone can call them.
136
- Apply all eight non-negotiable rules above. Auth first, then rate limit, then validate, then authorize the specific operation.
137
- Use `try/catch` and never leak internal detail in error messages.
138
- Validate content type and size; treat all input as untrusted.
139
- `NextRequest` gives `nextUrl` (parsed pathname/searchParams) and cookie helpers; `NextResponse` gives `json()`, `redirect()`, `rewrite()`.
140
- If `OPTIONS` is undefined, Next.js generates it and sets `Allow` from the other exported methods.
141

142
### CORS
143

144
- **Never set `Access-Control-Allow-Origin: '*'` on a handler that returns user-specific or authenticated data.** This is the reflexive fix for a CORS error and it makes the endpoint readable by any site the user visits.
145
- If cross-origin access is genuinely needed, allowlist specific origins and echo only matching ones. `*` is incompatible with credentials anyway.
146
- A CORS error on a same-origin call usually means the URL is wrong, not that CORS needs loosening.
147

148
### Skeleton
149

150
```ts
151
import { auth } from '@/lib/auth';
152
import { checkRateLimit } from '@/lib/rate-limit';
153
import { schema } from './schema';
154

155
export async function POST(request: Request) {
156
  const session = await auth();
157
  if (!session) return new Response(null, { status: 401 });
158

159
  const { limited } = await checkRateLimit(request);
160
  if (limited) {
161
    return Response.json({ error: 'Too many requests' }, { status: 429 });
162
  }
163

164
  const parsed = schema.safeParse(await request.json());
165
  if (!parsed.success) {
166
    return Response.json({ error: 'Bad request' }, { status: 400 });
167
  }
168

169
  try {
170
    // doWork authorizes against session.user.id — not just "is logged in"
171
    const result = await doWork(parsed.data, session.user.id);
172
    return Response.json(result);
173
  } catch (error) {
174
    console.error(error);
175
    return new Response('Internal error', { status: 500 });
176
  }
177
}
178
```
179

180
## Caching and revalidation
181

182
**`fetch` is NOT cached by default** (changed in Next 15). Uncached fetches block rendering until they resolve.
183

184
- To cache, use the `use cache` directive.
185
- To avoid blocking, wrap the fetching component in `<Suspense>` and stream at request time.
186

187
### Never cache session-dependent output
188

189
This is the most dangerous mistake in this file, because no authentication check will catch it. If a cached route or function renders anything derived from the current user, the first user's data gets served to everyone who hits the cache afterwards. The auth check passed — for someone else.
190

191
```ts
192
// ❌ one user's dashboard, served to all of them
193
'use cache'
194
export async function Dashboard() {
195
  const session = await auth()
196
  return <Orders orders={await getOrders(session.user.id)} />
197
}
198
```
199

200
Before adding `use cache`, a `revalidate` value, or any cache wrapper, ask: **is this output identical for every visitor?**
201

202
- **Safe to cache:** marketing pages, public blog posts, product catalogues, docs, static reference data.
203
- **Never cache:** anything reading `cookies()`, `headers()`, or a session; anything keyed to a user, tenant, or org; anything behind a login.
204
- If a page mixes both, cache the shared parts and put the personalized parts behind their own `<Suspense>` boundary so they render per-request.
205

206
### Choosing a revalidation API
207

208
After a mutation, pick by what needs to change:
209

210
| API              | Behaviour                                                                                                                        | Use when                                      |
211
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- |
212
| `updateTag`      | Immediate expiry. The re-render shipped in the action response **waits** for fresh data. Server Actions only.                    | The user must see their own write immediately |
213
| `revalidateTag`  | Stale-while-revalidate. Next reads get the stale value; refresh happens in background. The action's re-render does **not** wait. | Background freshness is fine                  |
214
| `revalidatePath` | Invalidate by URL path                                                                                                           | One route affected, tagging is overkill       |
215
| `refresh`        | Refetch the current route's RSC Payload without invalidating cached data. Server Actions only.                                   | View depends on state outside the cache       |
216

217
Notes:
218

219
- Default to `updateTag` for read-your-own-writes. Reaching for `revalidateTag` there is a common bug — the user won't see their change.
220
- None of these throw. `redirect` **does** throw a control-flow exception, so nothing after it runs — call revalidation _before_ `redirect`.
221
- Avoid waterfalls: start independent requests then `await Promise.all([...])`. Use `Promise.allSettled` if one failure shouldn't fail everything.
222

223
## Framework-level security (and its limits)
224

225
Next.js provides these automatically for Server Actions. **None of them know who your users are or what they may do.** They do not replace the non-negotiable rules above.
226

227
- CSRF: `Origin` compared against `Host` / `X-Forwarded-Host`. Configure `experimental.serverActions.allowedOrigins` in `next.config.js` for proxy/CDN domains.
228
- 1MB default body limit — configure `experimental.serverActions.bodySizeLimit` if needed.
229
- Encrypted action IDs; unused Server Functions stripped from client bundles.
230
- Inline-action closure variables are encrypted. Self-hosted/multi-instance: set a stable `NEXT_SERVER_ACTIONS_ENCRYPTION_KEY` across instances.
231

232
### `proxy.ts` (renamed from `middleware.ts` in Next 16)
233

234
- Only one per project; use `config.matcher` to scope it.
235
- Good for coarse redirects and early rejection.
236
- **Not a security boundary.** It runs too far from your data to know whether _this_ user may touch _this_ row, and it has historically been bypassable (see CVE-2025-29927). Auth still gets checked at the data access point, every time.
237

238
### Secrets
239

240
- Never hardcode secrets in frontend code.
241
- Treat every `NEXT_PUBLIC_*` value as public — it is inlined into the browser bundle. If it is prefixed, it is published.
242
- Use the `server-only` package for modules that must never be bundled client-side. It converts an accidental client import into a build error instead of a leak.
243

244
## Browser APIs
245

246
- Guard browser-only APIs: check `typeof window !== "undefined"` before `window`/`document`.
247
- Put browser-only code in `useEffect` inside a Client Component.
248
- `dynamic(..., { ssr: false })` is only allowed **inside a Client Component** in the App Router. It will error in a Server Component.
249

250
## Rendering, hydration, streaming
251

252
- Avoid hydration mismatches: server-rendered HTML must match first client render. No `Date.now()` / `Math.random()` in initial render output without guards.
253
- Prefer **granular `<Suspense>`** over route-level `loading.tsx`.
254
  - Place `<Suspense>` **above** the async component, not inside it.
255
  - Use `key` on a boundary when it should re-suspend on dependency change.
256
- `loading.tsx` caveat: if a **layout** reads uncached or runtime data (`cookies()`, `headers()`, an uncached fetch), it will **not** fall back to a same-segment `loading.tsx` — it blocks navigation until the layout finishes. Wrap that access in its own `<Suspense>`, or move the fetch into `page.tsx`.
257
- Design meaningful loading states (skeletons matching the real layout), not bare spinners.
258

259
## Routing and params
260

261
- `params` and `searchParams` are **Promises** — `await` them.
262
- Reading `searchParams`, `cookies()`, or `headers()` in a Server Component makes that route dynamic. That is often correct; just be deliberate about it.
263
- Treat everything in `params` and `searchParams` as attacker-controlled. See non-negotiable rule 2.
264
- For simple query-string reads on the client, `useSearchParams()` in a Client Component avoids server-side dynamic rendering. It requires a `<Suspense>` boundary when the route is statically rendered.
265
- Type Route Handler context with the generated `RouteContext<'/path/[id]'>` helper.
266

267
## Client-side fetching
268

269
Server Components cover most needs. Fetch on the client only for:
270

271
- Data depending on client-only Web APIs (geolocation, storage, audio, file).
272
- Frequently polled data.
273

274
Use SWR or React Query for these — **not** Server Actions, which are dispatched sequentially, and not hand-rolled `useEffect` fetches, which get caching and race conditions wrong.