Cursor Rules for
Next.js

This rule provides guidance for Next.js development within Cursor, focusing on best practices for the App Router structure, component organization, and efficient state management techniques. It helps ensure your Next.js projects follow modern conventions and performance standards.

What this rule does

The Next.js rule in Cursor serves as a comprehensive guide for fullstack development using Next.js, particularly with the newer App Router architecture. It establishes conventions for:

• File structure and naming conventions
• Proper usage of Server and Client Components
• Export patterns and component organization
• State management optimization
• Performance best practices

These guidelines help maintain consistency across your Next.js projects while promoting patterns that enhance performance and developer experience.

Key Next.js conventions

App Router structure

The rule emphasizes using the App Router structure, which uses directory-based routing with page.tsx files within route directories. This approach, introduced in Next.js 13, replaces the older Pages Router system with a more intuitive and flexible routing mechanism.

Component organization

Several important component practices are recommended:

• Use kebab-case for directory names (e.g., components/auth-form)
• Use PascalCase for component files
• Prefer named exports over default exports:

// Recommended
export function Button() { 
  /* ... */ 
}

// Not recommended
export default function Button() { 
  /* ... */ 
}

Client vs. Server Components

The rule provides guidance on the effective use of React Server Components (RSC) and Client Components:

• Server Components are the default in Next.js App Router
• Only mark components with 'use client' when they require client-side interactivity
• Minimize the use of client components to improve performance
• Create small client component wrappers around interactive elements
• Wrap client components in Suspense with appropriate fallback UI

State management

The rule recommends optimizing state management by:

• Using server components for data fetching rather than client-side fetching
• Leveraging React Server Actions for form handling
• Using URL search parameters for shareable state
• Utilizing the nuqs library for URL search parameter state management

Using Next.js in Cursor

The Next.js rule (nextjs.mdc) is configured to automatically activate when you're working with JavaScript or TypeScript files. The glob pattern **/*.js,**/*.jsx,**/*.ts,**/*.tsx ensures that the AI gets this context whenever you're editing relevant files.

When active, this rule guides Cursor's AI to make recommendations and generate code that follows Next.js best practices. For example:

• When creating new components, the AI will suggest named exports rather than default exports
• When implementing interactive features, it will recommend patterns that minimize client components
• When organizing your project, it will follow the proper directory structure conventions

You can also manually invoke this rule by typing @nextjs in Cursor's Cmd-K interface or chat if you need explicit Next.js guidance for a specific task.

Usage tips

Minimizing client components

One of the key performance optimizations in modern Next.js is minimizing the use of client components. Consider this pattern for interactive elements:

// ButtonWrapper.tsx - Small client component
'use client'
 
import { useState } from 'react'
 
export function ButtonWrapper({ children }) {
  const [count, setCount] = useState(0)
  
  return (
    <button onClick={() => setCount(count + 1)}>
      {children} {count}
    </button>
  )
}

// Page.tsx - Server component that uses the client component
import { ButtonWrapper } from './ButtonWrapper'
 
export default function Page() {
  // This component remains a server component
  return (
    <div>
      <h1>My Page</h1>
      <ButtonWrapper>Click me</ButtonWrapper>
    </div>
  )
}

Using URL state effectively

For state that needs to be shareable or persisted between page loads, the rule recommends using URL search parameters with the nuqs library:

'use client'
 
import { useQueryState } from 'nuqs'
 
export function FilterComponent() {
  // This will manage the 'category' state in the URL
  const [category, setCategory] = useQueryState('category')
  
  return (
    <select 
      value={category || ''}
      onChange={(e) => setCategory(e.target.value)}
    >
      <option value="">All</option>
      <option value="electronics">Electronics</option>
      <option value="clothing">Clothing</option>
    </select>
  )
}

Following these practices will help you build performant, maintainable Next.js applications that leverage the full capabilities of the framework.