What Is a.cursorrules File?

A .cursorrules file is a configuration file that provides project-specific context to Cursor IDE's AI. Think of it as a system prompt for your codebase — every AI interaction (autocomplete, chat, Composer) uses these rules as context.

Without rules, Cursor's AI uses generic patterns. With rules, it understands your naming conventions, preferred libraries, file structure, and coding standards. The difference in output quality is dramatic.

Basic.cursorrules Setup

#.cursorrules ## Project Context
This is a React 18 + TypeScript + Tailwind CSS web application.
Backend: Supabase (PostgreSQL, Auth, Edge Functions).
State management: TanStack Query for server state, zustand for client state. ## Coding Standards
- Use functional components with hooks (no class components)
- Prefer named exports over default exports
- Use TypeScript strict mode — no `any` types
- Component files: PascalCase (UserProfile.tsx)
- Utility files: camelCase (formatDate.ts)
- Use `cn()` utility from @/lib/utils for conditional classes ## File Structure
- src/components/ — Reusable UI components
- src/pages/ — Route-level page components
- src/hooks/ — Custom React hooks
- src/lib/ — Utility functions
- src/types/ — TypeScript type definitions ## Anti-Patterns (AVOID)
- Do NOT use inline styles — use Tailwind classes
- Do NOT use `useEffect` for data fetching — use TanStack Query
- Do NOT store sensitive data in localStorage
- Do NOT use `var` — use `const` or `let` ## Preferred Patterns
- Use shadcn/ui components from @/components/ui/
- Error boundaries for route-level components
- Zod for runtime validation
- React Hook Form for form handling

Advanced Rules

Framework-Specific Context

## Supabase Integration
- Import client from @/integrations/supabase/client
- Always use RLS policies — never bypass with service key on client
- Use `supabase.auth.getUser()` for auth checks
- Edge functions go in supabase/functions/ ## API Patterns
- Use TanStack Query with queryKey conventions: ['entity', id]
- Mutations should invalidate related queries
- Handle loading, error, and empty states in every data component

Team Conventions

## Git Conventions
- Commit messages: type(scope): description
- Branch naming: feature/ticket-id-short-description
- PR descriptions must include "What" and "Why" sections ## Testing
- Unit tests: Vitest + React Testing Library
- Test files: __tests__/ComponentName.test.tsx
- Test user interactions, not implementation details

Multi-File Rules (.cursor/rules/)

For larger projects, you can use the .cursor/rules/ directory with multiple rule files:

.cursor/ rules/ general.md # Overall project context frontend.md # React/UI conventions backend.md # API/database patterns testing.md # Test writing standards

Community Rule Libraries

The Cursor community maintains rule libraries on GitHub for popular stacks:

  • cursor-rules/react-typescript: React 18 + TypeScript best practices
  • cursor-rules/python-fastapi: FastAPI + SQLAlchemy conventions
  • cursor-rules/rust-axum: Rust web development patterns
  • cursor-rules/nextjs: Next.js App Router conventions

Start with a community template and customize for your project. The key is specificity — the more detail you provide about your conventions, the better Cursor performs.

Tips for Effective Rules

  • Be specific: "Use shadcn/ui Button component from @/components/ui/button" beats "use a UI library"
  • Include examples: Show what good code looks like in your project
  • List anti-patterns: Tell the AI what NOT to do — it's surprisingly effective
  • Update regularly: As conventions evolve, update rules to match
  • Commit to git: The whole team benefits from consistent AI behavior
  • Keep it under 2,000 words: Longer rules dilute the AI's attention

Conclusion

A well-crafted .cursorrules file is one of the highest-ROI investments for Cursor users. Spend 30 minutes writing rules, save hours of correcting AI output. For more Cursor productivity, check our Cursor tips and tricks guide. And if you're evaluating Cursor against alternatives, see our Claude Code vs Cursor vs Copilot comparison.