Getting Started with Cursor Rules

Understanding Rule Components

Every cursor rule consists of several key components that define its behavior:

Rule Structure

• Name: A descriptive identifier for your rule
• Pattern: The text pattern or regex that triggers the rule
• Action: What the rule should do when triggered
• Scope: File types or contexts where the rule applies

Common Rule Types

1. Code Completion Rules

These rules help autocomplete common patterns:

{
  "name": "React Component Template",
  "trigger": "rfc",
  "expansion": "import React from 'react';\n\nconst $1 = () => {\n  return (\n    <div>\n      $0\n    </div>\n  );\n};\n\nexport default $1;",
  "scope": ["javascript", "typescript", "jsx", "tsx"]
}

2. Code Formatting Rules

Rules that enforce consistent formatting:

{
  "name": "Console Log Format",
  "pattern": "console\\.log\\(([^)]+)\\)",
  "replacement": "console.log('🐛 Debug:', $1)",
  "scope": ["javascript", "typescript"]
}

3. Import Organization Rules

Keep your imports clean and organized:

{
  "name": "Group Imports",
  "pattern": "^import.*$",
  "action": "sort-imports",
  "options": {
    "groups": ["builtin", "external", "internal", "relative"],
    "newlinesBetweenGroups": true
  }
}

Advanced Rule Configuration

Using Variables and Placeholders

Cursor rules support variables that make them more flexible:

{
  "name": "API Endpoint Creator",
  "trigger": "api",
  "expansion": "const ${1:endpoint} = async (${2:params}) => {\n  const response = await fetch('/api/${1}', {\n    method: '${3:GET}',\n    headers: {\n      'Content-Type': 'application/json',\n    },\n    ${4:body: JSON.stringify(params),}\n  });\n  return response.json();\n};",
  "scope": ["javascript", "typescript"]
}

Conditional Rules

Create rules that adapt based on context:

{
  "name": "Smart Component Import",
  "condition": "file.extension === 'tsx' && project.hasReact",
  "pattern": "import ([A-Z]\\w+)",
  "action": "add-component-props",
  "template": "interface ${1}Props {\n  // Add props here\n}\n\nconst ${1}: React.FC<${1}Props> = (props) => {"
}

Best Practices

1. Start Simple

Begin with basic rules and gradually add complexity:

{
  "name": "Simple Console",
  "trigger": "cl",
  "expansion": "console.log($0)",
  "scope": ["javascript", "typescript"]
}

2. Use Descriptive Names

Choose clear, descriptive names for your rules:

// ✅ Good
"name": "React Functional Component with Props"

// ❌ Bad
"name": "rfc"

3. Test Your Patterns

Always test your regex patterns to ensure they work correctly:

// Test your patterns in the browser console
const pattern = /import\s+{\s*([\w\s,]+)\s*}\s+from\s+['"]([\/\w\-@.]+)['"]/;
const testString = "import { useState, useEffect } from 'react'";
console.log(pattern.test(testString)); // Should return true

4. Organize by Category

Group related rules together:

{
  "categories": {
    "React": [
      "React Functional Component",
      "React Hook",
      "React Context"
    ],
    "TypeScript": [
      "Interface Definition",
      "Type Declaration",
      "Generic Function"
    ],
    "Testing": [
      "Jest Test",
      "React Testing Library",
      "Mock Function"
    ]
  }
}

Common Use Cases

1. Framework-Specific Templates

Next.js Page Template

{
  "name": "Next.js Page",
  "trigger": "nextpage",
  "expansion": "import { NextPage } from 'next';\n\ninterface ${1:Home}Props {\n  // Add props here\n}\n\nconst ${1}: NextPage<${1}Props> = (props) => {\n  return (\n    <div>\n      <h1>${2:Page Title}</h1>\n      $0\n    </div>\n  );\n};\n\nexport default ${1};",
  "scope": ["typescript", "tsx"]
}

Express Route Handler

{
  "name": "Express Route",
  "trigger": "route",
  "expansion": "app.${1:get}('/${2:path}', async (req, res) => {\n  try {\n    $0\n    res.json({ success: true });\n  } catch (error) {\n    res.status(500).json({ error: error.message });\n  }\n});",
  "scope": ["javascript", "typescript"]
}

2. Error Handling Patterns

{
  "name": "Try-Catch Block",
  "trigger": "tryc",
  "expansion": "try {\n  $0\n} catch (error) {\n  console.error('Error:', error);\n  // Handle error appropriately\n}",
  "scope": ["javascript", "typescript"]
}

3. Documentation Templates

{
  "name": "JSDoc Function",
  "trigger": "jsdoc",
  "expansion": "/**\n * ${1:Description}\n * @param {${2:type}} ${3:param} - ${4:description}\n * @returns {${5:type}} ${6:description}\n * @example\n * ${7:example usage}\n */",
  "scope": ["javascript", "typescript"]
}

Troubleshooting Common Issues

Issue 1: Rule Not Triggering

Problem: Your rule doesn't activate when expected.

Solutions:

• Check the scope is correct for your file type
• Verify the pattern syntax
• Ensure there are no conflicting rules

Issue 2: Incorrect Pattern Matching

Problem: Rule triggers at wrong times or doesn't match intended text.

Solutions:

• Use regex testing tools to validate patterns
• Add word boundaries to prevent partial matches
• Escape special characters properly

Issue 3: Performance Issues

Problem: Too many rules slow down the editor.

Solutions:

• Limit rule scope to specific file types
• Use efficient regex patterns
• Remove unused rules regularly

Sharing and Importing Rules

Exporting Your Rules

# Export rules to a file
cursor --export-rules my-rules.json

Importing Community Rules

# Import rules from a file
cursor --import-rules community-rules.json

Popular Rule Collections

• React Development Pack: Comprehensive rules for React projects
• TypeScript Essentials: Must-have rules for TypeScript development
• API Development Kit: Rules for building REST APIs
• Testing Suite: Rules for writing tests efficiently

Next Steps

Now that you understand the basics of cursor rules, here are some next steps:

1. Create Your First Custom Rule: Start with a simple snippet you use frequently
2. Explore Community Rules: Browse shared rule collections
3. Join the Community: Share your rules and learn from others
4. Advanced Techniques: Learn about rule chaining and conditional logic

Recommended Resources

• Official Cursor Rules Documentation
• Community Rule Repository
• Advanced Pattern Matching Guide
• Rule Performance Optimization

Conclusion

Cursor rules are a powerful way to customize your development environment and boost productivity. Start with simple rules and gradually build more complex automation as you become comfortable with the system.

Remember, the best rules are those that solve real problems in your daily workflow. Take note of repetitive tasks and consider how rules might help automate them.

Happy coding! 🚀