Next.js Cursor Rules Template

Every component in the app/ directory is a Server Component until a 'use client' directive says otherwise — but Cursor's instincts were formed on client-side React, so it reaches for useState, onClick handlers, and even window and localStorage in files that render on the server. The result is either a runtime crash ("window is not defined") or a reflexive 'use client' at the top of the file that quietly drags the entire subtree, its imports included, into the client bundle.

The rule "prefer server components by default; add 'use client' only when needed" flips Cursor's prior. In practice the winning pattern is to push the directive down: keep the page and layout on the server, and extract the interactive leaf — the search box, the like button — into its own small client file. The boundary is directional, and that is worth stating in your own custom rules too: a Server Component may render a Client Component, but a Client Component can only receive server-rendered content through children or other props, never by importing a server file.

In the App Router you fetch data by awaiting it inside an async Server Component — no getServerSideProps, no useEffect-then-setState, and no route handler that exists only so a client component can fetch from your own app. Cursor generates all three of these legacy patterns unprompted, which is why the template states the positive rule ("fetch data in server components; use async/await directly") instead of assuming the model knows the current idiom.

Caching is the subtler trap. Cursor's training data spans the era when fetch was aggressively cached by default and the current one where it is not: in Next.js 16, an unannotated fetch blocks rendering and runs on every request. The template's guidance to reach for next: { revalidate }, generateStaticParams, and explicit revalidation makes Cursor declare its caching intent instead of inheriting whichever default it happens to remember. Route handlers (route.ts) remain in the rules for what they are actually for — webhooks and endpoints consumed by clients outside your Next.js app.

The single most common build error in AI-generated Next.js 16 code is synchronous access to params and searchParams. Cursor writes const { slug } = params because that was correct for years; since the async-params change it must be const { slug } = await params, and dynamic APIs like cookies() and headers() must be awaited too. A one-line rule fixes an error the model will otherwise reproduce in every dynamic route it touches.

This is also why the template's TypeScript section tells Cursor to use the generated PageProps and LayoutProps helpers rather than hand-rolling prop interfaces. These globals are typed per-route (PageProps<'/blog/[slug]'>) and already model params as a Promise — so the type system catches the sync-access mistake even when Cursor forgets the rule. Hand-written interfaces, which Cursor loves to invent, encode the stale shape and hide the bug.

Ask Cursor for a form and, unguided, it scaffolds the 2022 stack: an onSubmit handler, a fetch('/api/submit'), a route handler, and hand-rolled loading state. The "use server actions for form mutations" rule collapses that into one function — a 'use server' mutation passed to the form's action prop, with revalidatePath handling the cache afterwards. Fewer files, progressive enhancement for free, and no API surface to keep in sync with its only caller.

Server Actions come with constraints Cursor must be reminded of, and a custom rule in the generator is a good place for them: every action is a public HTTP endpoint regardless of where it is defined, so it must validate its inputs and check authorization itself — never trust that "only my form calls this". The remaining optimization rules exist for the same reason as the Actions rule: plain <img>, <a>, and @font-face are what the model reaches for first, and next/image, next/link, and next/font are strictly better in a Next.js app but only get used when the rules demand them.