Skip to main content

Best Practices for .cursor/rules

.cursor/rules is a powerful feature that helps teams maintain consistent coding standards and improve collaboration. This guide covers best practices for setting up and managing rules effectively.

Understanding .cursor/rules​

.cursor/rules is a configuration system that:

  • Defines project-wide coding standards
  • Automates code organization
  • Enforces consistent patterns
  • Improves team collaboration

Basic Setup​

Creating the Rules File​

Create a .cursor/rules file in your project root:

mkdir .cursor
touch .cursor/rules

Basic Structure​

A typical rules file structure:

version: 1.0
rules:
  - name: "Component Structure"
    pattern: "src/components/**/*.{ts,tsx}"
    template: |
      import React from 'react'
      
      interface ${ComponentName}Props {
        // props
      }
      
      export const ${ComponentName}: React.FC<${ComponentName}Props> = () => {
        return (
          <div>
            {/* component content */}
          </div>
        )
      }

  - name: "Service Layer"
    pattern: "src/services/**/*.ts"
    template: |
      import { ApiClient } from '../utils/apiClient'
      
      export class ${ServiceName}Service {
        private client: ApiClient
        
        constructor() {
          this.client = new ApiClient()
        }
        
        // service methods
      }

Best Practices​

1. Consistent Naming Conventions​

Use clear, descriptive names for rules:

rules:
  - name: "React Component"
    description: "Standard React component structure"
    pattern: "src/components/**/*.tsx"

  - name: "API Service"
    description: "REST API service template"
    pattern: "src/services/**/*.ts"

2. Modular Organization​

Group related rules together:

rules:
  # Component Rules
  - name: "Component/Functional"
    pattern: "src/components/**/*.tsx"
    
  - name: "Component/Class"
    pattern: "src/components/**/*.class.tsx"
    
  # Service Rules
  - name: "Service/REST"
    pattern: "src/services/rest/**/*.ts"
    
  - name: "Service/GraphQL"
    pattern: "src/services/graphql/**/*.ts"

3. Template Variables​

Use descriptive template variables:

rules:
  - name: "Component Template"
    pattern: "src/components/**/*.tsx"
    template: |
      interface ${ComponentName}Props {
        ${PropName}: ${PropType}
      }
      
      export const ${ComponentName} = ({
        ${PropName}
      }: ${ComponentName}Props) => {
        return (
          <div>
            {${PropName}}
          </div>
        )
      }

4. Documentation​

Include clear documentation in rules:

rules:
  - name: "API Service"
    description: |
      Template for API service classes.
      Includes standard CRUD operations and error handling.
    pattern: "src/services/**/*.ts"
    template: |
      /**
       * ${ServiceName} Service
       * Handles ${ServiceDescription}
       */
      export class ${ServiceName}Service {
        // implementation
      }

5. Error Handling​

Include error handling patterns:

rules:
  - name: "Service Error Handling"
    pattern: "src/services/**/*.ts"
    template: |
      try {
        // service logic
      } catch (error) {
        if (error instanceof ApiError) {
          // handle API errors
        } else {
          // handle other errors
        }
        throw error
      }

Advanced Patterns​

1. Conditional Templates​

Use conditions in templates:

rules:
  - name: "Component with Props"
    pattern: "src/components/**/*.tsx"
    template: |
      ${HasProps ? `
      interface ${ComponentName}Props {
        // props
      }
      ` : ''}
      
      export const ${ComponentName}${HasProps ? ': React.FC<${ComponentName}Props>' : ''} = () => {
        // implementation
      }

2. Shared Patterns​

Define reusable patterns:

patterns:
  typescript-header: |
    /**
     * @file ${FileName}
     * @description ${FileDescription}
     * @created ${Date}
     */

rules:
  - name: "Component"
    pattern: "src/components/**/*.tsx"
    template: |
      ${patterns.typescript-header}
      // component implementation

Optimization Tips​

  1. File Organization

    • Group related files together
    • Use consistent directory structures
    • Follow naming conventions

  2. Template Efficiency

    • Keep templates focused and specific
    • Avoid redundant code
    • Use shared patterns for common elements

  3. Performance Considerations

    • Limit pattern complexity
    • Use specific file patterns
    • Avoid overly broad matches

Common Patterns​

React Components​

rules:
  - name: "React Functional Component"
    pattern: "src/components/**/*.tsx"
    template: |
      import React from 'react'
      import styles from './${ComponentName}.module.css'
      
      export interface ${ComponentName}Props {
        // props
      }
      
      export const ${ComponentName}: React.FC<${ComponentName}Props> = () => {
        return (
          <div className={styles.container}>
            {/* component content */}
          </div>
        )
      }

Service Classes​

rules:
  - name: "Service Class"
    pattern: "src/services/**/*.ts"
    template: |
      import { injectable } from 'inversify'
      import { ApiClient } from '@/utils/apiClient'
      
      @injectable()
      export class ${ServiceName}Service {
        constructor(private apiClient: ApiClient) {}
        
        async getAll(): Promise<${EntityName}[]> {
          return this.apiClient.get('/${entityPath}')
        }
        
        async getById(id: string): Promise<${EntityName}> {
          return this.apiClient.get(`/${entityPath}/${id}`)
        }
      }
  • Configuration Guide
  • Team Collaboration
  • Code Organization

Conclusion​

Effective use of .cursor/rules can significantly improve code consistency and team productivity. By following these best practices, you can create maintainable and scalable code structures.

  • Advanced Cursor Configuration
  • Team Workflow Optimization
  • Code Generation Patterns