Skip to content

README.md

Latest commit

 

History

History
196 lines (151 loc) · 5.73 KB

README.md

File metadata and controls

196 lines (151 loc) · 5.73 KB

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

📄 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.