name: nextjs-react-redux-typescript-cursor-rules
description: Comprehensive Next.js, React, Redux, and TypeScript development guidelines covering SOLID principles, component architecture, and best practices.

Next.js React Redux TypeScript Cursor Rules

Complete development guidelines for building maintainable, scalable applications with Next.js, React, Redux Toolkit, and TypeScript.

Development Philosophy

• Produce maintainable, scalable code following SOLID principles
• Favor functional and declarative approaches over imperative styles
• Prioritize type safety and static analysis
• Embrace component-driven architecture

Code Style Standards

• Indentation: Use tabs
• Strings: Use single quotes (unless escaping needed)
• Semicolons: Omit unless disambiguation required
• Operators: Space around infix operators
• Functions: Space before declaration parentheses
• Equality: Always use === over ==
• Line length: Maximum 80 characters
• Conditionals: Use braces for multi-line if statements
• Collections: Trailing commas in multiline arrays/objects

Naming Conventions

Prefixes

• Event handlers: handle (e.g., handleClick)
• Booleans: verbs (e.g., isLoading, hasError, canSubmit)
• Custom hooks: use (e.g., useAuth, useForm)

React Best Practices

Components

• Use functional components with TypeScript interfaces
• Define components using function keyword
• Extract reusable logic into custom hooks
• Apply composition patterns properly
• Leverage React.memo() strategically
• Implement cleanup in useEffect hooks

Performance

• Use useCallback for memoizing functions
• Apply useMemo for expensive computations
• Avoid inline function definitions in JSX
• Implement code splitting via dynamic imports
• Use proper key props in lists (never use index)

Next.js Best Practices

Core

• Use App Router for routing
• Implement metadata management
• Apply proper caching strategies
• Implement error boundaries

Components

• Use built-in components: Image, Link, Script, Head
• Implement loading states
• Use appropriate data fetching methods

Server Components

• Default to Server Components
• Use URL query parameters for server state
• Apply use client only when necessary:
• Event listeners
• Browser APIs
• State management
• Client libraries

TypeScript Implementation

• Enable strict mode
• Define clear interfaces for props, state, and Redux structure
• Use type guards for undefined/null safety
• Apply generics for flexibility
• Leverage utility types (Partial, Pick, Omit)
• Prefer interface over type for objects
• Use mapped types for dynamic type variations

UI and Styling

Libraries

• Shadcn UI: Consistent, accessible components
• Radix UI: Customizable primitives
• Composition patterns: Modularity

Styling

• Tailwind CSS utility-first approach
• Mobile-first responsive design
• Dark mode via CSS variables or Tailwind's dark mode
• Accessible color contrast ratios
• Consistent spacing values
• CSS variables for theme colors

State Management

Local State

• useState for component-level state
• useReducer for complex state
• useContext for shared state

Global State (Redux Toolkit)

• Use createSlice for combined state/reducers/actions
• Normalize state structure
• Use selectors for access encapsulation
• Separate concerns by feature (avoid monolithic slices)

Error Handling and Validation

Forms

• Zod for schema validation
• React Hook Form integration
• Clear error messaging

Error Boundaries

• Catch and handle React tree errors gracefully
• Log errors to external services (e.g., Sentry)
• Display user-friendly fallback UIs

Testing

Unit Testing

• Jest and React Testing Library
• Arrange-Act-Assert pattern
• Mock external dependencies and API calls

Integration Testing

• Focus on user workflows
• Proper test environment setup/teardown
• Selective snapshot testing
• Use testing utilities (screen in RTL)

Accessibility (a11y)

• Semantic HTML
• Accurate ARIA attributes
• Full keyboard navigation
• Proper focus management
• Accessible color contrast
• Logical heading hierarchy
• Accessible interactive elements
• Clear error feedback

Security

• Input sanitization to prevent XSS
• DOMPurify for HTML sanitization
• Proper authentication methods

Internationalization (i18n)

• next-i18next for translations
• Locale detection
• Number and date formatting
• RTL support
• Currency formatting

Documentation

• JSDoc for all public functions, classes, methods, interfaces
• Complete sentences with proper punctuation
• Clear, concise descriptions
• Proper markdown, code blocks, links, headings, lists
• Examples when appropriate