Master Your Next.js Conventions with a Bulletproof .cursorrules File

A useful .cursorrules file does not try to describe every preference in a Next.js project. It gives an AI coding agent a map of the repository, the boundaries it must respect, examples to copy, and checks that prove the change belongs. The goal is fewer invented components, fewer accidental client boundaries, and smaller diffs that a human can review.

Cursor’s Rules documentation now describes project rules in .cursor/rules as version-controlled .mdc files, with metadata such as description, globs, and alwaysApply. It also documents AGENTS.md as a Markdown alternative. If an older project still calls its root file .cursorrules, treat that as a compatibility convention and verify the current behavior in the editor version your team uses. Do not assume that a filename from an old prompt has the same loading semantics as the current rules system.

Start with a repository map

The first section should tell the agent where routes, components, data access, server-only code, tests, and generated files live. A tree is more useful than “this is a Next.js app.” It removes the most common guess: where should this new file go?

## Repository map

src/app/             routes, layouts, route handlers
src/components/ui/   reusable visual primitives, no business logic
src/features/        feature modules and feature-specific components
src/server/          server-only queries and integrations
src/lib/             shared utilities and typed clients
public/              static assets
 tests/              tests mirroring source ownership

Rules:
- Route files stay under src/app/.
- Server-only modules stay under src/server/.
- Generated output is never edited by hand.
- Read the closest existing feature before adding a new one.

Adapt the map to the actual repository. A copied tree that does not match reality is worse than no tree because it sends the agent confidently to the wrong directory.

Include a short explanation for unusual folders. If src/components/ui contains primitives while src/features contains product behavior, say that directly. If route groups or parallel routes have special ownership, document the rule beside the map.

Define import and export rules

Import conventions are easy for an agent to follow when they are concrete. Specify the alias, export style, grouping order, and restrictions on server-only modules.

## Imports and exports

- Use the @/* alias for src/*.
- Prefer named exports for reusable components and utilities.
- Import from leaf files rather than broad barrel files in feature code.
- Keep React and framework imports first, third-party imports second,
  project aliases third, and relative imports last.
- Never import src/server/** from a client component.
- Keep environment reads in server-only modules.
- Do not add a dependency without explaining the need first.

The last three lines prevent a class of bugs that often looks like a styling or build problem. A client component importing a server-only helper can expose the wrong boundary. A random environment read can fail in the browser. An unreviewed dependency can expand the attack and maintenance surface.

Write the replacement pattern as well as the prohibition. “Never import server code into a client component” becomes more actionable when the rule says to pass a serializable value from a server component or call an approved server action.

Keep the server boundary explicit

In the App Router, the default should be the least client-side surface that satisfies the feature. Your rules should explain when a file may use client-only behavior and where data fetching belongs.

## Server and client boundaries

- Keep pages and layouts server-rendered unless they need client behavior.
- Add a client directive only for hooks, event handlers, or browser APIs.
- Fetch initial data in the server-owned layer and pass serializable props down.
- Put mutations behind the repository's approved server boundary.
- Never read secrets or privileged service credentials in client code.
- Keep loading, error, and empty states beside the feature they serve.

The rule should match your code, not a generic framework tutorial. If your project uses a different data layer or action pattern, name it. If a feature uses a client cache for pagination, document that exception and its reason.

A small client island is easier to test and reason about than a page that becomes client-side because one nested button needed an event handler. Make the leaf interactive, keep the page’s data boundary visible, and ask the agent to explain any proposed boundary expansion.

Replace vague bans with allowed pairs

“Write clean code” is not a rule. “Never use raw image elements” is incomplete unless the repository tells the agent what to use instead.

## Allowed replacements

- For responsive images, use the repository image component with dimensions.
- For feature validation, use the existing schema helper and error shape.
- For dialogs, reuse the shared dialog primitive and focus behavior.
- For server reads, use the approved typed data client.
- For styling, use existing tokens before introducing a one-off value.
- For a new dependency, stop and ask with the reason and alternatives.

Pairing a forbidden pattern with its replacement keeps the agent productive. It also makes code review faster: a reviewer can check whether the approved pattern was used rather than debating a vague style preference.

Avoid absolute rules that your own codebase violates. If legacy code still contains raw image elements or default exports, scope the rule to new and edited files, then create a migration plan separately. A rule that is visibly false teaches the agent to ignore the rest.

Add route and rendering conventions

Next.js projects often need conventions for route files, metadata, loading states, errors, and not-found behavior. State the decisions your team has actually made.

## Routes

- Route entry files contain routing and composition, not large feature implementations.
- Feature-specific helpers live in an underscore-prefixed folder beside the route.
- Every data-heavy segment defines a loading state.
- Every user-facing segment defines an error and empty state where applicable.
- Metadata is defined through the repository's current metadata convention.
- Route handlers export the supported HTTP methods explicitly.
- Do not move a route or rename a segment without listing backlink and deep-link impact.

Do not copy an arbitrary directory recipe into every application. The right folder name depends on your repository and the version of the framework you run. The rule file should reduce local ambiguity, not replace current product documentation.

Include one real component example

Agents follow examples better than abstract descriptions. Point to one primitive and one complete feature that already match the desired structure.

## Reference examples

For a reusable button, read:
  src/components/ui/button.tsx

Match its export style, variant naming, accessibility attributes, and test shape.
Do not create a second button primitive.

For a server-owned feature, read:
  src/features/orders/page.tsx

Match its data boundary, loading state, error handling, and client leaf.
Do not move the page to the client to avoid understanding the existing pattern.

Keep examples current. If a reference file is deprecated, replace it before the rules file. One accurate example is more valuable than a dozen stale links.

Add a change contract

A rules file defines durable context. The prompt for each task should define the current scope and done state. Include a standard contract in the file so agents and humans use the same review language.

## Change contract

Before editing:
- list the files you plan to touch
- name the reference feature you will follow
- state any assumption that is not visible in the repository

After editing:
- summarize behavior and files changed
- report passed, failed, and not-run checks
- call out new dependencies and boundary changes
- do not claim a check passed if it was not run

This turns an agent response into evidence rather than a confidence statement. It also catches scope drift before a large diff reaches review.

For a practical four-anchor prompt that combines conventions, examples, scope, and done criteria, read how to prompt Cursor. For repository structure that helps an agent find the right code, read agent-readable repository structure.

Keep rules small and layered

A single enormous file becomes another document the agent and humans stop reading. Start with cross-cutting rules, then add path-scoped rules for components, server code, tests, or native configuration. Cursor’s current rules model supports project rules that can be applied always, by file pattern, intelligently from a description, or manually.

Use one rule for a decision that should hold everywhere. Use a scoped rule for a decision that only applies to a directory. Do not repeat the same rule in five places; duplicated instructions drift and create conflicts.

Review the rules file when the repository changes:

• A folder moves.
• A data client is replaced.
• A server boundary changes.
• A test command changes.
• A dependency becomes approved or forbidden.
• A reference component is deprecated.

Treat these edits as codebase changes. Review them, commit them, and explain the reason in the change history.

Test the rules with a small task

Do not evaluate a rules file by reading it once. Give an agent a bounded task that should expose the decisions:

Add an empty state to the existing orders list.

- First read the project rules and the orders feature.
- Use the existing empty-state component and data boundary.
- Touch only the orders feature and its focused test.
- Do not add a dependency or move the page to the client.
- Run the focused test and type check.
- Report the files changed and any check not run.

Inspect whether the agent chose the expected files, reused the expected component, preserved the server boundary, and stopped at the requested scope. If it fails, improve the rule or reference example instead of adding more prose to the task prompt.

Test a negative case too. Ask for a new feature that would tempt the agent to edit a generated file, read a secret in client code, or add an unapproved dependency. The correct result may be a question or a refusal to proceed until the boundary is clarified.

Connect rules to the product foundation

OTF’s templates page verifies a free MIT component SDK and a free AI configurations pack for Cursor, Claude, and Lovable. That is the relevant OTF connection: a project-context starting point can give an agent reusable conventions and components, but it does not know your application’s route ownership, data policy, or release checks automatically.

For production acceptance checks after an agent edits the repository, read AI coding agent acceptance checklist. For conventions that cover a broader production repository, read production repository conventions for AI coding agents.

A bulletproof rules file is not a wall of restrictions. It is a compact map of the repository, the allowed patterns, the boundaries that protect production behavior, and the evidence required before a change is accepted. Keep it factual, keep examples current, and make every important “never” point to an approved way forward.

Sources

• Cursor Rules documentation
• OTF templates