nextjs-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

| Convention | Usage | |------------|-------| | PascalCase | Components, type definitions, interfaces | | kebab-case | Directory and file names (e.g., user-profile.tsx) | | camelCase | Variables, functions, methods, hooks, properties, props | | UPPERCASE | Environment variables, constants, global configurations |

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