Next.js
React framework with server components, file-based routing and a build-in server runtime.
The rule
This is the whole text, exactly as your agent receives it. Nothing is held back for the paid tier.
Server by default
- Components are Server Components unless the file starts with
'use client'. - Add
'use client'as far down the tree as possible. On a layout it turns the entire subtree into client code and the bundle balloons. - Data fetching, database access and secrets belong in Server Components.
Environment variables
NEXT_PUBLIC_*is inlined into the browser bundle. Everything else is server-only.- Never add the prefix to fix an
undefinedin a client component — that publishes the value to every visitor. Move the code that reads it to the server instead. - Mark server-only modules with
import 'server-only'so a wrong import fails the build rather than leaking.
Route handlers and Server Actions
- Both are public HTTP entry points.
'use server'means "runs on the server", not "only my code can call it". - Validate input and check authorisation in every one, the same as a REST endpoint.
Caching
- Be explicit:
next: { revalidate: n }orcache: 'no-store'. - Reading cookies or headers opts a route out of static rendering — know which routes are dynamic rather than finding out in production.
Rendering
- No
Date.now(),Math.random()orwindowduring render — hydration mismatches. next/imagewith explicit dimensions for anything above the fold.
Never
- Never put a secret in a client component or a
NEXT_PUBLIC_*variable. - Never suppress a type error to get a build through.
6 formats, one per tool
Each tab is the file that tool actually reads, at the path it actually looks in. Knowing where each one looks is most of the work of supporting it.
---
description: Next.js conventions
globs: ["app/**", "src/app/**", "next.config.*", "**/*.tsx"]
alwaysApply: false
---
# Next.js
## Server by default
- Components are Server Components unless the file starts with `'use client'`.
- Add `'use client'` as far down the tree as possible. On a layout it turns the
entire subtree into client code and the bundle balloons.
- Data fetching, database access and secrets belong in Server Components.
## Environment variables
- `NEXT_PUBLIC_*` is **inlined into the browser bundle**. Everything else is
server-only.
- Never add the prefix to fix an `undefined` in a client component — that
publishes the value to every visitor. Move the code that reads it to the
server instead.
- Mark server-only modules with `import 'server-only'` so a wrong import fails
the build rather than leaking.
## Route handlers and Server Actions
- Both are **public HTTP entry points**. `'use server'` means "runs on the
server", not "only my code can call it".
- Validate input and check authorisation in every one, the same as a REST
endpoint.
## Caching
- Be explicit: `next: { revalidate: n }` or `cache: 'no-store'`.
- Reading cookies or headers opts a route out of static rendering — know which
routes are dynamic rather than finding out in production.
## Rendering
- No `Date.now()`, `Math.random()` or `window` during render — hydration
mismatches.
- `next/image` with explicit dimensions for anything above the fold.
## Never
- Never put a secret in a client component or a `NEXT_PUBLIC_*` variable.
- Never suppress a type error to get a build through.
Hand-written by the module author, frontmatter and all. It is the source the four derived formats are rendered from, so a correction lands here first.
What else this module writes
The rule is one file of several. Selecting Next.js contributes all of this too — merged with every other module you pick, with conflicts resolved rather than duplicated.
NEXT_PUBLIC_APP_URLrequiredPublic URL of this deployment, used for absolute links and redirects.NEXT_PUBLIC_API_URLoptionalBase URL of an external API called from the browser.NODE_ENVoptionalSet by Next.js. Do not override it manually.Advisory history
Every time this rule turned out to be wrong, and what we did about it.
This rule has been accurate since it was published. That is a fact about the rule, not a promise about the future — which is the whole reason this section exists.
Pro tells you the day a correction lands that affects a repo you actually have.
See what Pro adds →Rules people add alongside this one
The wizard picks the rest of the stack with you, writes all 6 formats, and leaves a manifest so check can tell you when any of it drifts.