These 14 Next.js prompts help ChatGPT, Claude, Claude Code and Codex write App Router code that matches Next.js 16: where to put the Server and Client boundary, how to cache with Cache Components, how to write safe Server Actions, how to move from middleware to proxy, and how to upgrade without breaking routes. Every prompt asks the model for code plus the reasoning you need to review it.
For framework-free React work such as splitting components or removing Effects, use the React prompts. For styling, see the Tailwind CSS prompts.
How to use these prompts
Copy a prompt into your AI tool and fill the blanks in double braces. A blank with a colon has a default: {{version:16}} means Next.js 16 unless you change it.
State your version and router every time. Next.js 16 made big changes, and the version 16 upgrade guide lists them: params, searchParams, cookies() and headers() can only be read asynchronously, revalidateTag takes a second cacheLife argument, middleware is renamed to proxy, and Turbopack is the default bundler. A model that doesn't know your version will mix old and new APIs.
Paste the whole route segment, not one file. A page.tsx alone hides the layout.tsx above it, the loading.tsx beside it and the data functions it imports. In an agent, name the folder and ask it to read everything inside first.
Ask for the docs page it relied on. The Next.js docs are versioned and current, and asking "which docs page supports this?" catches invented APIs fast.
How do you structure an App Router app?
1. Plan routes and layouts for a feature
Use it before creating folders. Layouts, loading states and error boundaries are cheap to plan and annoying to move later.
I'm adding {{feature:a team settings area}} to a Next.js {{version:16}} App Router app.
Screens: {{screens}}
Who can see them: {{access:signed-in team admins only}}
Propose the folder structure under app/: route segments, dynamic segments,
route groups, and which segments need their own layout.tsx, loading.tsx,
error.tsx and not-found.tsx. For each layout, say what it renders and what
data it needs. Show the tree, then explain any choice that affects what
re-renders on navigation.
2. Push the Client boundary down
The Server and Client Components page explains that once a file has "use client", all of its imports and the components it renders directly go into the client bundle. This prompt moves the directive to the smallest interactive piece.
This Next.js page has "use client" near the top of the tree, so too much
ships to the browser.
{{files}}
Find the smallest components that truly need the client (state, event
handlers, Effects, browser APIs, custom hooks). Move "use client" to those
files only, keep data fetching in Server Components, and pass Server
Components to Client Components as children where that helps. Props crossing
the boundary must be serializable. Show the new files and list what moved
from client to server.
3. Fix a hydration mismatch
Hydration errors usually come from values that differ between the server render and the first client render.
I get a hydration mismatch in my Next.js app.
Error text: {{error}}
Component: {{component}}
List the likely causes in this code, ranked: dates, random values, locale
formatting, browser-only APIs read during render, invalid HTML nesting, or
extensions changing the DOM. For the top cause, show the fix that keeps the
server and first client render identical. Don't silence the warning with
suppressHydrationWarning unless the difference is intentional, and say so if
you use it.
How do you fetch and cache data in Next.js 16?
4. Fix blocking-route errors after turning on Cache Components
With cacheComponents: true, the caching docs say uncached data and runtime APIs must either be cached with use cache or wrapped in <Suspense>, and the dev overlay flags each case.
I enabled cacheComponents in Next.js {{version:16}} and now get blocking-route
insights on this route.
Route files: {{files}}
Dev overlay messages: {{messages}}
For each flagged access, decide: cache it with "use cache" plus cacheLife
(the same for every user), or stream it behind <Suspense> (per request or
per user, such as cookies or searchParams). Keep as much of the page in the
static shell as possible by awaiting params and cookies deep in the tree,
not in the layout. Show the changed code and a table of each access and the
choice you made.
5. Cache a data function with tags
The caching docs recommend pairing every use cache with a cacheLife profile. Tags let you expire the right entries after a write.
Add caching to these Next.js data functions using "use cache", cacheLife and
cacheTag from next/cache.
{{functions}}
How often the data changes: {{freshness:a few times a day}}
What writes it: {{writers:an admin form and a nightly import}}
Pick a cacheLife profile for each function and explain why. Add tags that
let me expire one record and the whole list separately. Remember that
arguments become part of the cache key, so flag any argument that would
create too many entries or leak per-user data into a shared cache.
6. Choose how to refresh data after a write
Next.js 16 has several options that behave differently. The upgrade guide describes updateTag as a Server Actions-only API with read-your-writes semantics, while revalidateTag serves stale content while fresh data loads.
After this mutation in my Next.js {{version:16}} app, the UI shows old data.
Mutation: {{action}}
Where the data is read and cached: {{reads}}
Tell me which to use and why: updateTag, revalidateTag with a cacheLife
profile, revalidatePath, or refresh. Consider whether the user who made the
change must see it immediately, whether other users can see stale data for
a while, and whether the call happens in a Server Action or a Route
Handler. Show the corrected code.
How do you write safe Server Actions and forms?
7. Write a Server Action with validation and pending state
Write a Server Action for {{task:creating a project}} in Next.js {{version:16}}.
Form fields: {{fields}}
Validation library: {{validator:Zod}}
Requirements: check the session and the user's permission inside the
action; validate every field and return field errors instead of throwing;
return only what the UI needs, never the raw database record; refresh the
affected data afterwards. Then write the form as a Client Component that
uses useActionState to show pending state and errors, with labels tied to
inputs and errors announced to screen readers.
8. Audit Server Actions for security
The data security guide warns that a page-level auth check does not extend to the Server Actions inside it, and recommends a server-only Data Access Layer. This prompt checks each action against that guide.
Audit every "use server" function in these files:
{{files}}
For each action, check: does it verify authentication inside the action;
does it check authorization for the specific resource (not just "logged
in"); are all arguments validated; does it return only what the client
needs; does database access go through a server-only module; could a
closure capture sensitive values? Output a table of action, issue,
severity and fix, then show the fixed code for the worst one.
How do you handle errors, routing and proxy?
9. Add loading, error and not-found states
error.tsx must be a Client Component and does not catch errors in the layout of the same segment. The error.js reference points to global-error.js for the root layout.
Add loading, error and not-found handling to this route segment:
{{files}}
Write loading.tsx with a skeleton that matches the real layout, error.tsx as
a Client Component with a retry button and logging, and not-found.tsx with a
helpful message and a link back. Call notFound() where a record doesn't
exist. Tell me which errors these files won't catch (for example errors in
this segment's own layout) and where to handle those instead.
10. Move middleware to proxy and tighten the matcher
The proxy.js reference notes that without a matcher, proxy runs on every request, including static files and images, and that auth must still be checked inside each Server Function.
Migrate this middleware.ts to proxy.ts for Next.js 16:
{{middleware}}
Rename the file and function, keep the behavior the same, and write a
matcher that excludes _next/static, _next/image and public assets. If the
code relies on the edge runtime, stop and tell me, because proxy runs on
Node.js only. List any auth logic here that must also exist inside Server
Actions or route handlers, and suggest moving work out of proxy where a
layout, redirect in next.config or route handler would be simpler.
How do you upgrade and migrate a Next.js app?
11. Plan an upgrade to Next.js 16
Plan the upgrade of this app from Next.js {{from:15}} to 16.
package.json: {{package_json}}
next.config: {{next_config}}
Notable features we use: {{features:middleware, next/image with remote images, a custom webpack config}}
Give me ordered steps: Node.js and TypeScript version checks, the upgrade
codemod, the async request API codemod if needed, the middleware to proxy
rename, revalidateTag calls that need a cacheLife argument, next/image
default changes that affect us, and custom webpack config versus Turbopack.
For each step, list how to verify it. Don't enable cacheComponents or React
Compiler as part of the upgrade unless I ask.
12. Move one Pages Router page to the App Router
The App Router migration guide says app and pages can run side by side for page-by-page migration, and that navigating between the two routers is a hard navigation.
Migrate this Pages Router page to the App Router without changing what
users see:
{{page}}
Map getServerSideProps, getStaticProps or getStaticPaths to Server
Component data fetching and generateStaticParams. Replace next/router with
next/navigation hooks, next/head with the metadata API, and move any context
providers into a Client Component. Keep interactive parts in a Client
Component. List what I need to test, including links between this page and
pages that stay in pages/.
13. Generate metadata for a dynamic route
Write generateMetadata for the dynamic route {{route:app/blog/[slug]/page.tsx}}
in Next.js {{version:16}}.
Data available: {{data:title, summary, cover image URL, published date}}
Await params, reuse the same cached data function the page uses so the
data isn't fetched twice, and return title, description, canonical URL,
Open Graph and Twitter fields. Handle the missing-record case with
notFound(). Show the code and explain where the title template from the
root layout applies.
14. Find what makes a route slow or heavy
Next.js 16 removed the size and First Load JS columns from next build output, and the upgrade guide suggests measuring with tools such as Lighthouse instead.
This Next.js route feels slow: {{route}}
Symptoms: {{symptoms:slow first load and a long wait before content appears}}
Files: {{files}}
Find the likely causes: large Client Components, client-side data fetching
that could move to the server, sequential awaits that could run in
parallel, missing Suspense boundaries, unoptimized images or fonts, and
heavy third-party scripts. Rank them by expected impact, show the fix for
the top two, and tell me what to measure in Lighthouse before and after.
How do you keep a Next.js prompt library current?
Next.js changes fast, so date your prompts. When a new major version ships, reread the upgrade guide and update the prompts that mention caching, routing or config. The Next.js Cache Components optimizer skill and the Next.js dev loop skill pages cover ready-made skills that bring this guidance into an agent automatically. To turn one of the prompts above into your own skill, paste it into the SKILL.md generator.
If you want these prompts one search away, Kipt keeps them as Markdown in a private GitHub repo you own. Blanks like {{version:16}} stay fillable, tags and Cmd+K search find the right prompt, and skills you save there install into Claude Code or Codex with one command.