Cursor Rules for TypeScript/Next.js + Supabase

A comprehensive set of Cursor IDE rules for building modern, scalable web applications with TypeScript, Next.js App Router, and Supabase.

🚀 What This Provides

This repository contains carefully crafted Cursor rules that enforce best practices for:

• RSC-First Development: Server components by default, client components when needed
• Type Safety: Strict TypeScript with no any types
• Supabase Integration: Proper server/client patterns with RLS
• Next.js App Router: Modern routing, data fetching, and caching patterns
• UI Components: shadcn/ui + Tailwind CSS with accessibility in mind
• Security: Authorization checks, RLS enforcement, input validation
• Testing: Unit tests with Vitest, E2E with Playwright
• Performance: Optimized patterns and DX improvements

📁 Rule Structure

The rules are organized into logical modules:

.cursor/rules/
├── 00-role-style.mdc           # Core development philosophy & style
├── 10-structure-naming.mdc     # File structure & naming conventions
├── 20-env-secrets.mdc          # Environment variables & secrets
├── 30-supabase.mdc            # Supabase integration patterns
├── 40-nextjs-data-caching.mdc # Next.js RSC, data fetching & caching
├── 50-api-and-actions.mdc     # API routes & server actions
├── 60-ui-forms.mdc            # UI components & form handling
├── 70-security-and-authz.mdc  # Security & authorization
├── 80-testing-and-quality.mdc # Testing strategies
├── 90-performance-and-dx.mdc  # Performance & developer experience
└── 99-checklists-and-templates.mdc # Code templates & checklists

🛠 Setup & Usage

Quick Start

1. Copy the rules to your project:

   # In your Next.js project root
   mkdir -p .cursor/rules
   cp path/to/cursorrules/.cursor/rules/* .cursor/rules/

2. Cursor will automatically apply these rules to your development workflow

Tech Stack Assumptions

These rules are optimized for projects using:

• Next.js 14+ with App Router
• TypeScript (strict mode)
• Supabase for database & auth
• Tailwind CSS + shadcn/ui
• React Hook Form + Zod
• Vitest + Playwright

🎯 Key Patterns Enforced

Server-First Architecture

// ✅ Server component by default
export default async function Page() {
  const data = await supabaseServer().from('items').select('*')
  return <ItemList items={data} />
}

// ✅ Client component when needed
'use client'
export function InteractiveButton() {
  const [count, setCount] = useState(0)
  return <button onClick={() => setCount(count + 1)}>{count}</button>
}

Proper Supabase Patterns

// ✅ Server-side data access
import { supabaseServer } from '@/lib/supabase/server'
const data = await supabaseServer().from('table').select('*')

// ✅ Client-side mutations via server actions
'use server'
export async function createItem(data: FormData) {
  const result = await supabaseServer()
    .from('items')
    .insert(validatedData)
  revalidatePath('/items')
}

Type-Safe API Routes

// ✅ Validated inputs and typed responses
const Schema = z.object({ id: z.string().uuid() })

export async function GET(req: Request) {
  const parsed = Schema.safeParse(params)
  if (!parsed.success) {
    return NextResponse.json({ error: 'Invalid input' }, { status: 422 })
  }
  // ... typed response
}

📚 What's Included

Development Standards

• Consistent file naming and organization
• TypeScript strict mode configurations
• Import/export patterns
• Error handling strategies

Ready-to-Use Templates

• Server action boilerplate
• API route handler templates
• Environment variable setup
• Supabase client configuration

Security Best Practices

• RLS policy enforcement
• Input validation patterns
• Authorization checks
• Secret management

Testing Guidelines

• Component testing with Vitest
• E2E testing with Playwright
• Test organization and naming

🔧 Customization

Modifying Rules

Each rule file is a standalone module. You can:

1. Disable specific rules by removing the file
2. Customize patterns by editing the .mdc files
3. Add project-specific rules by creating new files

Adding Your Own Rules

Create new .mdc files following this format:

---
description: Your rule description
globs: ["**/*.{ts,tsx}"]
alwaysApply: true
---

# YOUR RULE TITLE
- Rule description and guidelines

🎨 Code Style Highlights

• Variables: isLoading/hasError pattern
• Files: kebab-case, Components: PascalCase
• Functions: Small, composable, pure when possible
• Dates: UTC with date-fns
• No classes: Prefer functions and hooks

🚦 Pre-commit Checklist

The rules include an automated checklist for code submissions:

• Component needs client features? Add "use client"
• Mutations use server actions with Zod validation
• Environment variables added to /lib/env.ts
• Supabase queries respect RLS policies
• UI components are accessible
• Lint, typecheck, and tests pass

🤝 Contributing

1. Fork this repository
2. Make your changes to the rule files
3. Test with a sample Next.js project
4. Submit a pull request with clear descriptions

📖 Related Resources

• Next.js App Router Docs
• Supabase JavaScript Client
• shadcn/ui Components
• Cursor IDE Documentation

📄 License

MIT License - feel free to use these rules in your projects!

---

These rules are designed to accelerate development while maintaining code quality and consistency across your team.