Cursor Rules Config

Cursor Rules Config

Configure project-specific AI behavior through Cursor's rules system. The modern approach uses .cursor/rules/*.mdc files; the legacy .cursorrules file is still supported but deprecated.

Rules System Architecture

Modern Project Rules (.cursor/rules/*.mdc)

Each .mdc file contains YAML frontmatter followed by markdown content:

---
description: "Enforce TypeScript strict mode and functional patterns"
globs: "src/**/*.ts,src/**/*.tsx"
alwaysApply: false
---
# TypeScript Standards

- Use `const` over `let`, never `var`
- Prefer pure functions over classes
- All functions must have explicit return types
- Use discriminated unions over enums

Frontmatter fields:

Rule Types by alwaysApply + globs Combination

File Naming Convention

Use kebab-case with .mdc extension. Names should describe the rule's scope:

.cursor/rules/
  typescript-standards.mdc
  react-component-patterns.mdc
  api-error-handling.mdc
  testing-conventions.mdc
  database-migrations.mdc
  security-requirements.mdc

Create new rules via: Cmd+Shift+P > New Cursor Rule

Complete Project Rules Example

`.cursor/rules/project-context.mdc` (always-on):

---
description: "Core project context and conventions"
globs: ""
alwaysApply: true
---
# Project: E-Commerce Platform

Tech stack: Next.js 15, TypeScript 5.7, Prisma ORM, PostgreSQL, Tailwind CSS 4.
Package manager: pnpm. Monorepo with turborepo.

## Conventions
- API routes in `app/api/` using Route Handlers
- Server Components by default, `"use client"` only when needed
- Error boundaries at layout level
- All monetary values stored as integers (cents)
- Dates stored as UTC, displayed in user timezone

`.cursor/rules/react-patterns.mdc` (glob-scoped):

---
description: "React component standards for TSX files"
globs: "src/**/*.tsx,app/**/*.tsx"
alwaysApply: false
---
# React Component Rules

- Export components as named exports, not default
- Props interface named `{Component}Props`
- Use `forwardRef` for components accepting `ref`
- Colocate styles in `.module.css` files
- Server Components: no `useState`, `useEffect`, or event handlers

// Correct pattern export interface ButtonProps { variant: 'primary' | 'secondary'; children: React.ReactNode; onClick?: () => void; }

export function Button({ variant, children, onClick }: ButtonProps) { return ( <button className={styles[variant]} onClick={onClick}> {children} </button> ); }

`.cursor/rules/api-routes.mdc` (glob-scoped):

---
description: "API route handler patterns"
globs: "app/api/**/*.ts"
alwaysApply: false
---
# API Route Standards

- Always validate request body with Zod
- Return typed `NextResponse.json()` responses
- Use consistent error response shape: `{ error: string, code: string }`
- Wrap handlers in try/catch with structured logging

import { NextRequest, NextResponse } from 'next/server'; import { z } from 'zod';

const CreateOrderSchema = z.object({ items: z.array(z.object({ productId: z.string().uuid(), quantity: z.number().int().positive(), })), });

export async function POST(req: NextRequest) { try { const body = await req.json(); const parsed = CreateOrderSchema.parse(body); const order = await createOrder(parsed); return NextResponse.json(order, { status: 201 }); } catch (err) { if (err instanceof z.ZodError) { return NextResponse.json( { error: 'Validation failed', code: 'INVALID_INPUT', details: err.issues }, { status: 400 } ); } return NextResponse.json( { error: 'Internal server error', code: 'INTERNAL_ERROR' }, { status: 500 } ); } }

Legacy .cursorrules Format

Place a .cursorrules file in project root. Plain markdown, no frontmatter:

# Project Rules

You are working on a Django REST Framework API.

## Stack
- Python 3.12, Django 5.1, DRF 3.15
- PostgreSQL 16 with pgvector extension
- Redis for caching and Celery broker
- pytest for testing

## Conventions
- ViewSets over function-based views
- Always use serializer validation
- Custom exceptions inherit from `APIException`
- All endpoints require authentication unless explicitly marked
- Use `select_related` and `prefetch_related` to avoid N+1 queries

## Code Style
- Type hints on all function signatures
- Docstrings on all public methods (Google style)
- Max function length: 30 lines

Migration: .cursorrules to .cursor/rules/

Split a monolithic .cursorrules into scoped .mdc files:

1. Create .cursor/rules/ directory 2. Extract global context into an alwaysApply: true rule 3. Extract language/framework rules into glob-scoped rules 4. Delete .cursorrules after verifying all rules load

Referencing Files in Rules

Use @file syntax to include additional context files when a rule is applied:

---
description: "Database schema context for migration files"
globs: "prisma/**/*.prisma,drizzle/**/*.ts"
alwaysApply: false
---
Reference these files for schema context:
@prisma/schema.prisma
@docs/data-model.md

Debugging Rules

1. Open Chat and type @Cursor Rules to see which rules are active 2. Check glob patterns match your files: open a file, then verify the rule appears in context pills 3. Rules with alwaysApply: true always show; glob rules only appear when matching files are in context

Enterprise Considerations

• Version control: Commit .cursor/rules/ to git -- rules are project documentation
• Team alignment: Use alwaysApply: true for team-wide standards
• Sensitive data: Never put API keys, secrets, or credentials in rules files
• Rule size: Keep individual rules focused and under 200 lines; split large rules into multiple files
• Audit trail: Rules changes appear in git history for compliance review

Resources

• Cursor Rules Documentation
• MDC Rules Deep Dive
• awesome-cursorrules

Advanced Configuration

Advanced Configuration

Context Section

context:
  # Key architectural decisions
  architecture: |
    We use a feature-based architecture where each feature
    (auth, products, cart) contains its own components, hooks,
    and API calls. Shared utilities go in lib/.

  # Important patterns
  patterns: |
    - Data fetching: useQuery from @tanstack/react-query
    - Forms: react-hook-form with zod validation
    - State: Zustand for global state
    - API: tRPC for type-safe APIs

  # Things to avoid
  avoid: |
    - Class components
    - Redux (we use Zustand)
    - CSS-in-JS (we use Tailwind)
    - Direct fetch() calls (use our api client)

Examples Section

examples:
  component: |
    // Example component structure
    import { useState } from 'react';
    import { Button } from '@/components/ui';

    interface Props {
      title: string;
      onAction: () => void;
    }

    export function MyComponent({ title, onAction }: Props) {
      const [loading, setLoading] = useState(false);

      return (
        <div className="p-4">
          <h2 className="text-lg font-bold">{title}</h2>
          <Button onClick={onAction} loading={loading}>
            Action
          </Button>
        </div>
      );
    }

  api-route: |
    // Example API route
    import { NextRequest, NextResponse } from 'next/server';
    import { z } from 'zod';

    const schema = z.object({
      name: z.string().min(1),
    });

    export async function POST(req: NextRequest) {
      try {
        const body = await req.json();
        const data = schema.parse(body);
        // Process...
        return NextResponse.json({ success: true });
      } catch (error) {
        return NextResponse.json(
          { error: 'Invalid request' },
          { status: 400 }
        );
      }
    }

Testing Section

testing:
  framework: vitest
  patterns:
    - Use describe/it blocks
    - Follow AAA pattern (Arrange, Act, Assert)
    - Mock external dependencies
    - Test edge cases and error paths

  example: |
    import { describe, it, expect, vi } from 'vitest';
    import { render, screen } from '@testing-library/react';
    import { MyComponent } from './MyComponent';

    describe('MyComponent', () => {
      it('renders title correctly', () => {
        render(<MyComponent title="Test" onAction={vi.fn()} />);
        expect(screen.getByText('Test')).toBeInTheDocument();
      });

      it('calls onAction when button clicked', async () => {
        const onAction = vi.fn();
        render(<MyComponent title="Test" onAction={onAction} />);
        await userEvent.click(screen.getByRole('button'));
        expect(onAction).toHaveBeenCalled();
      });
    });

Basic Configuration

Basic Configuration

Minimal Example

# .cursorrules

# Project language and framework
language: typescript
framework: react

# Key coding rules
rules:
  - Use functional components
  - Prefer async/await over callbacks
  - Always handle errors explicitly

Standard Template

# .cursorrules

project: my-awesome-app
description: E-commerce platform built with Next.js

language: typescript
framework: nextjs
styling: tailwindcss
testing: vitest

rules:
  # Code Style
  - Use TypeScript strict mode
  - Prefer const over let
  - Use arrow functions for callbacks
  - Maximum line length: 100 characters

  # React Patterns
  - Use functional components only
  - Prefer hooks over HOCs
  - Use React Query for data fetching
  - Handle loading and error states

  # Architecture
  - Follow feature-based folder structure
  - Keep components under 200 lines
  - Extract business logic to hooks
  - Use dependency injection for services

naming:
  files: kebab-case
  components: PascalCase
  functions: camelCase
  constants: SCREAMING_SNAKE_CASE
  types: PascalCase with suffix (UserDTO, ProductResponse)

imports:
  order:
    - react, next (framework)
    - third-party packages
    - @/components
    - @/hooks
    - @/lib
    - @/types
    - relative imports

Error Handling Reference

--- [Tons of Skills](https://tonsofskills.com) by [Intent Solutions](https://intentsolutions.io) | [jeremylongshore.com](https://jeremylongshore.com)

Examples

Example: Basic TypeScript Project Configuration Request: "Configure cursor rules for a React TypeScript project" Result: Creates .cursorrules with TypeScript strict mode, functional components, and Tailwind styling rules

Example: Adding Custom Naming Conventions Request: "Add naming conventions for components and hooks" Result: Adds naming section with PascalCase for components, camelCase for functions, kebab-case for files

--- [Tons of Skills](https://tonsofskills.com) by [Intent Solutions](https://intentsolutions.io) | [jeremylongshore.com](https://jeremylongshore.com)

Framework-Specific Templates

Framework-Specific Templates

Next.js App Router

# .cursorrules for Next.js App Router

framework: nextjs-app-router
version: "14"

rules:
  - Use App Router conventions (app/ directory)
  - Server Components by default
  - "use client" only when needed
  - Use Server Actions for mutations
  - Implement loading.tsx and error.tsx

file-conventions:
  - page.tsx for routes
  - layout.tsx for layouts
  - loading.tsx for suspense
  - error.tsx for error boundaries
  - not-found.tsx for 404s

Express/Node.js Backend

# .cursorrules for Express API

framework: express
database: postgresql
orm: prisma

rules:
  - Use async/await for all async operations
  - Implement proper error handling middleware
  - Validate all inputs with zod
  - Use dependency injection for testability
  - Follow REST conventions

structure:
  - routes/ for Express routers
  - controllers/ for request handlers
  - services/ for business logic
  - repositories/ for data access
  - middleware/ for Express middleware

Python FastAPI

# .cursorrules for FastAPI

language: python
framework: fastapi
version: "0.100+"

rules:
  - Use Pydantic models for validation
  - Implement proper dependency injection
  - Use async where beneficial
  - Follow PEP 8 style guide
  - Type hints on all functions

structure:
  - app/routers/ for route handlers
  - app/models/ for Pydantic models
  - app/services/ for business logic
  - app/db/ for database operations

Tips For Effective Rules

Tips for Effective Rules

Be Specific

# Vague (less effective)
rules:
  - Write good code
  - Handle errors

# Specific (more effective)
rules:
  - Wrap async operations in try/catch
  - Return typed error responses using ApiError class
  - Log errors with context using logger.error()

Include Examples

# Examples help AI understand your patterns
error-handling-example: |
  try {
    const result = await someOperation();
    return { success: true, data: result };
  } catch (error) {
    logger.error('Operation failed', { error, context });
    throw new ApiError('OPERATION_FAILED', 500);
  }

Reference Project Files

context:
  reference-files:
    - See @lib/api-client.ts for API patterns
    - See @components/Button.tsx for component structure
    - See @hooks/useAuth.ts for hook patterns