Writing Effective .cursorrules for Next.js App Router

CursorRules provide a powerful way to customize Cursor AI’s behavior for your specific project. When working with Next.js App Router, defining clear conventions for file organization, component patterns, and API design helps the AI generate more accurate and consistent code. This guide shows you how to create effective CursorRules that align with Next.js App Router best practices.

Why CursorRules Matter for Next.js App Router

Next.js App Router introduces a different mental model compared to the traditional Pages Router. The file-system-based routing, Server Components by default, and the separation between client and server code require specific conventions that differ from other React frameworks. Without proper guidance, AI coding assistants often generate code that fights against these conventions.

CursorRules solve this problem by establishing project-specific guidelines that the AI follows during code generation. Rather than repeatedly explaining your project’s structure and preferences, you define them once in a configuration file that Cursor references throughout your development sessions.

Setting Up Your CursorRules File

Create a .cursorrules file in your Next.js project root. This file contains markdown-formatted instructions that Cursor reads and applies when generating code. The structure should cover your project’s naming conventions, component patterns, and architectural decisions.

# Next.js App Router Project Rules

## Project Structure
- Use App Router (not Pages Router)
- Keep routes in /app directory
- Place components in /components folder
- Store utility functions in /lib or /utils
- Put API routes in /app/api/[route]/route.ts
- Keep database queries in /lib/db
- Store type definitions in /types

## File Naming Conventions
- Use kebab-case for files: user-profile.tsx, api-handler.ts
- Use PascalCase for components: UserProfile.tsx, Button.tsx
- Use camelCase for utilities: formatDate.ts, fetchData.ts
- Prefix server-only files with server-: server-db.ts
- Group related files in directories: /components/users/, /lib/auth/

These rules establish a foundation that helps Cursor understand your project’s organization immediately.

Defining Component Patterns

Next.js App Router requires careful handling of client and server components. Your CursorRules should specify exactly when to use each type to prevent common mistakes.

## Component Guidelines

### Server Components (Default)
- Default to Server Components
- Use 'use client' only when needed: interactivity, hooks, browser APIs
- Keep data fetching in server components
- Pass serialized data to client components as props

### Client Components
- Add 'use client' directive at the top
- Use for: useState, useEffect, event handlers, custom hooks with state
- Keep client components as leaf nodes in the component tree
- Use for: interactive UI, forms, animations

### Component Structure
- Props should use TypeScript interfaces
- Extract complex logic into custom hooks
- Co-locate component styles with component file
- Use composition over inheritance

This guidance prevents the common mistake of adding ‘use client’ to every component, which defeats the performance benefits of Server Components.

API Route Conventions

API routes in App Router live in the /app/api directory and use route handlers instead of the traditional API routes. Your CursorRules should capture these differences clearly.

## API Route Guidelines

### Route Handlers
- Create in /app/api/[resource]/route.ts
- Use GET, POST, PUT, PATCH, DELETE exports
- Return Response with proper status codes
- Use NextResponse helper for JSON responses

### Request Handling
- Extract params from props: params { params: { id: string } }
- Parse request body: const body = await request.json()
- Validate with Zod schemas from /lib/schemas
- Handle errors with try-catch and return 400/500 status

### Response Format
- Use consistent response wrapper: { success: boolean, data?: T, error?: string }
- Return 404 for not found, 400 for bad request, 500 for server errors
- Set appropriate cache headers for GET requests

These patterns ensure Cursor generates API routes that follow Next.js conventions rather than mixing Pages Router patterns.

Database and Data Access Patterns

Most Next.js applications interact with databases. Your CursorRules should specify how to organize data access code and which patterns to use.

## Database Guidelines

### Query Organization
- Keep queries in /lib/db or /lib/server
- Use Prisma, Drizzle, or your chosen ORM
- Never expose database queries directly to client components
- Use Server Actions for data mutations

### Server Actions
- Create in /app/actions or co-located with related components
- Add 'use server' at function top
- Validate input with Zod
- Handle errors and return typed responses
- Use revalidatePath or redirect after mutations

TypeScript Configuration

TypeScript plays a crucial role in Next.js development. Your CursorRules should enforce type safety practices that work well with the framework.

## TypeScript Guidelines

### Type Definitions
- Define types in /types directory
- Use interfaces for object shapes, types for unions/primitives
- Extract response types from API routes
- Use generic types for reusable components

### Prop Types
- Always define component props with explicit types
- Use optional (?) for optional props
- Prefer specific types over any
- Use ReturnType for function prop types

Testing Conventions

Testing Next.js applications requires specific approaches for Server Components, Client Components, and API routes. Your CursorRules should guide test creation.

## Testing Guidelines

### Unit Tests
- Test utilities in /lib with Vitest
- Test components with React Testing Library
- Mock Server Components appropriately

### Integration Tests
- Use Playwright for E2E testing
- Test API routes with supertest or MSW
- Verify Server Action behavior

### Test Files
- Co-locate tests: component.tsx and component.test.tsx
- Use descriptive test names
- Follow AAA pattern: Arrange, Act, Assert

Applying Your CursorRules

After creating your .cursorrules file, Cursor automatically detects and applies these rules in your project. The AI references them when generating code, answering questions, or refactoring existing files. You can verify the rules are active by starting a new Cursor session and prompting the AI to generate a component—observe how it follows your conventions.

For optimal results, keep your CursorRules focused and specific. Include examples that demonstrate your expected patterns. Review and update the rules as your project evolves, especially when adopting new libraries or changing architectural decisions. Well-crafted CursorRules transform Cursor from a generic coding assistant into a project-aware partner that generates code matching your exact specifications.

Advanced CursorRules Patterns

Beyond basic structure, effective rules address common pain points:

Styling Strategy:

## Styling Guidelines
- Use Tailwind CSS exclusively
- Avoid inline styles
- Create reusable component classes in globals.css
- Use CSS modules for component-specific styles (Button.module.css)
- Color palette: primary=#3b82f6, secondary=#10b981, danger=#ef4444

Error Handling:

## Error Handling
- All try-catch blocks must include logging
- Server functions should return {success: boolean, error?: string}
- Use custom AppError class for application-specific errors
- Database errors should be logged but never exposed to clients

Authentication and Authorization:

## Auth Guidelines
- Use NextAuth.js for session management
- Check auth in middleware.ts for route protection
- All API routes must validate session before processing
- Store user ID in session; never trust client-provided IDs
- Admin routes require explicit role check in server action

Example CursorRules for Data-Heavy App

# Finance App CursorRules

## Numbers and Calculations
- Always use Decimal.js for currency, never floating point
- Round currency to 2 decimals only at display time
- Import Decimal from decimal.js; always new Decimal(value)
- Test calculations with edge cases (0, very large, negative)

## Database Queries
- Always use transactions for multi-step operations
- Index any column used in WHERE clause
- Use connection pooling; never create direct connections
- Cache read-heavy queries with 5-minute TTL

## Forms
- Use React Hook Form for all forms
- Validate with Zod schemas matching server-side validation
- Show field-level errors inline
- Disable submit button while loading

Measuring CursorRules Effectiveness

Track these metrics to evaluate your rules:

Rule relevance: Monitor how often Cursor suggests code that violates your rules. If violations happen frequently, the rule isn’t clear enough. Refine the language or add examples.

Time to acceptance: Measure how often you accept AI suggestions unchanged vs. modify them. High modification rates indicate rules aren’t translating to generated code.

Consistency across team: If multiple developers use the same .cursorrules, track whether generated code is consistent. Inconsistency suggests rules aren’t specific enough.

Code review friction: Track how many AI-generated code segments get feedback in code review. Declining feedback over time indicates improving rule clarity.

Common CursorRules Mistakes to Avoid

Too vague: “Use best practices” doesn’t guide AI. “Use snake_case for database columns, enforce via lowercase() in migrations” does.

Too long: Rules over 500 lines get ignored. Focus on high-impact patterns your team struggles with.

Too prescriptive: Don’t dictate every variable name. “Name state variables clearly” is weak. “State for feature flags should start with ‘is’: isMobileMenuOpen, isLoading” is actionable.

Never updated: Stale rules mislead the AI. Review quarterly and update for new libraries, patterns, or architectural decisions.

Lack of examples: Abstract rules produce abstract code. Include 2-3 inline code examples for every major guideline.

Integration with Team Workflow

Make CursorRules a team asset:

Version control: Commit .cursorrules to git. Review changes like any code.
Documentation: Link to detailed explanation in your wiki for each rule section.
Onboarding: Include CursorRules review in developer onboarding.
Feedback loop: When code review identifies repeated issues, add a rule addressing that pattern.

This transforms CursorRules from a personal customization into a shared tool for consistent code generation.

Performance Optimization Rules

Add specific guidance for performance-critical Next.js patterns:

## Performance Guidelines

### Images
- Use Next.js Image component exclusively
- Provide width and height props always
- Use priority={true} only for above-fold images
- Set sizes prop for responsive images

### Bundle Size
- Keep route components under 50KB
- Lazy load heavy components with dynamic()
- Use RSC for data-heavy pages to avoid hydration bloat

### Caching
- Use revalidatePath for mutations
- Set revalidate time in generateStaticParams
- Cache external API calls at 5-minute minimum

These detailed patterns prevent AI from generating performance antipatterns.

Built by theluckystrike — More at zovo.one