How I Set Up My Cursor Rules

Cursor Rules are instructions you give to Cursor's AI so it knows how to write code for your specific project. Think of it as teaching the AI your team's coding style and preferences.

What Are Cursor Rules?

They're just text instructions in plain English that tell the AI things like:

• How to structure your code
• What libraries to use
• What patterns to follow
• How to handle errors
• Coding conventions your team uses

The AI reads these rules every time it generates code, so everything stays consistent.

Why Use Them?

Consistency: No more fixing the AI's code to match your style Speed: The AI writes code that's ready to use immediately Quality: Fewer bugs because the AI follows your best practices

How to Set Them Up

1. Create a .cursorrules file in your project root
2. Write your rules in plain English
3. Commit the file so your team shares the same rules

That's it. Super simple.

My Cursor Rules

Here's what I use for my Next.js projects with TypeScript, Shadcn UI, and Zustand:

You are an expert in Next.js 15, React 19, TypeScript, Shadcn UI, Radix UI, Tailwind CSS v4, and Zustand state management.

Key Principles

- Write concise, technical responses with accurate TypeScript examples.
- Use functional, declarative programming. Avoid classes.
- Prefer iteration and modularization over duplication.
- Use descriptive variable names with auxiliary verbs (e.g., isLoading, hasError).
- Use lowercase with dashes for directories (e.g., components/auth-provider).
- Favor named exports for components.
- Use the Receive an Object, Return an Object (RORO) pattern.
- All code must be commented in English with comprehensive JSDoc documentation.

JavaScript/TypeScript

- Use "function" keyword for pure functions. Omit semicolons.
- Use TypeScript for all code. Prefer interfaces over types. Avoid enums, use const objects or maps.
- File structure: Imports, interfaces/types, exported component, subcomponents, helpers, static content.
- Avoid unnecessary curly braces in conditional statements.
- For single-line statements in conditionals, omit curly braces.
- Use concise, one-line syntax for simple conditional statements (e.g., if (condition) doSomething()).
- Use proper TypeScript generics and utility types for type safety.

Error Handling and Validation

- Prioritize error handling and edge cases:
  - Handle errors and edge cases at the beginning of functions.
  - Use early returns for error conditions to avoid deeply nested if statements.
  - Place the happy path last in the function for improved readability.
  - Avoid unnecessary else statements; use if-return pattern instead.
  - Use guard clauses to handle preconditions and invalid states early.
  - Implement proper error logging and user-friendly error messages.
  - Consider using custom error types or error factories for consistent error handling.
- Use Sonner for user-facing toast notifications.
- Log errors appropriately using custom debug logging utilities when available.

React/Next.js

- Use functional components and TypeScript interfaces.
- Use declarative JSX with proper accessibility attributes.
- Use function, not const, for components.
- Use Shadcn UI, Radix UI, and Tailwind CSS for components and styling.
- Implement responsive design with Tailwind CSS using mobile-first approach.
- Place static content and interfaces at file end.
- Use content variables for static content outside render functions.
- Minimize 'use client', 'useEffect', and 'setState'. Favor RSC (React Server Components).
- Wrap client components in Suspense with fallback when necessary.
- Use dynamic loading for non-critical components.
- Optimize images: WebP format, proper sizing, lazy loading.
- Use Next.js 15 App Router patterns consistently.
- Implement proper loading states and error boundaries.

State Management with Zustand

- Use Zustand for client-side state management following the established patterns.
- Structure stores with clear separation of state and actions.
- Use TypeScript interfaces for store state definitions.
- Implement proper state initialization and reset functionality.
- Use helper functions for complex state operations.
- Follow the established pattern of state/actions structure in store files.
- Implement proper error handling in async store actions.
- Use selectors for accessing specific parts of state in components.

File Upload and Processing

- Follow established patterns for file handling and validation.
- Implement proper file type validation and size limits.
- Use async/await for file processing operations.
- Handle ZIP file extraction appropriately.
- Implement proper progress tracking for upload operations.
- Use established file state management patterns (uploaded, stored, dimensionExceeded).
- Handle duplicate file names with unique naming strategies.

API Routes

- Use Next.js 15 App Router API routes with proper error handling.
- Implement proper request validation and response formatting.
- Use appropriate HTTP status codes and error messages.
- Handle file uploads with base64 encoding when established.
- Implement proper async error handling with try/catch blocks.
- Return consistent JSON response formats.

Authentication and Security

- Follow established authentication patterns using custom AuthProvider.
- Implement proper route protection with ProtectedRoute components.
- Use secure credential storage and retrieval patterns.
- Implement proper logout functionality with state cleanup.

Component Patterns

- Use established Shadcn UI component patterns and variants.
- Implement proper component composition with forwardRef when needed.
- Use class-variance-authority (cva) for component variants.
- Follow established styling patterns with Tailwind CSS utilities.
- Implement proper accessibility patterns with ARIA attributes.
- Use proper TypeScript props interfaces with optional/required fields.
- Follow the established pattern of using cn() utility for className merging.

Styling and UI

- Use Tailwind CSS v4 with established utility classes and custom CSS variables.
- Implement consistent color schemes using CSS custom properties.
- Use established glass-card and glow effects where appropriate.
- Follow mobile-first responsive design principles.
- Use proper spacing and layout patterns consistent with the existing design system.
- Implement dark/light theme support using next-themes.

Documentation and Comments

- All functions, components, and complex logic must have comprehensive JSDoc comments in English.
- Include parameter descriptions, return types, and usage examples where helpful.
- Document complex business logic and file processing workflows.
- Use inline comments for complex algorithms or non-obvious code sections.
- Document component props interfaces with clear descriptions.
- Include error handling documentation and expected behaviors.

Key Conventions

1. Rely on Next.js 15 App Router for routing and navigation.
2. Prioritize Web Vitals (LCP, CLS, FID) and performance optimization.
3. Minimize 'use client' usage:
   - Prefer server components and Next.js SSR features.
   - Use 'use client' only for Web API access in small components.
   - Avoid using 'use client' for data fetching or state management.
4. Follow established patterns for file upload, processing, and state management.
5. Use established repository patterns for server-side operations.
6. Implement proper error boundaries and loading states.
7. Use established debugging and logging utilities.
8. Follow the existing project structure and naming conventions.
9. Refer to Next.js 15 documentation for Data Fetching, Rendering, and Routing best practices.


Project-Specific Patterns

- Follow the established Zustand store patterns with proper state management.
- Use the established FileState interface and file processing workflows.
- Implement proper file size validation and limit enforcement.
- Use established component composition patterns for complex UI elements.
- Follow the repository pattern for server-side data operations.
- Use established authentication and route protection patterns.
- Implement proper notification patterns using Sonner toast system.

Tips for Writing Good Rules

Start simple: Begin with 5-10 basic rules and add more as you find patterns Be specific: Instead of "write good code", say "use TypeScript interfaces for all props" Keep them updated: Add new rules when you find yourself fixing the same issues

Want More Examples?

Check out this awesome collection of Cursor Rules for different frameworks and languages: https://github.com/PatrickJS/awesome-cursorrules?tab=readme-ov-file#contents