Best Cursor Rules

<picture>
  <source media="(prefers-color-scheme: dark)" srcset=".github/assets/logo-dark.png">
  <source media="(prefers-color-scheme: light)" srcset=".github/assets/logo-light.png">
  <img alt="Best Cursor Rules" src=".github/assets/logo-light.png" width="400">
</picture>

# Best Cursor Rules

**A curated collection of Cursor AI rules that actually work.**

Skip the guesswork. These rules are battle-tested, framework-specific, and ready to drop into your project.

---

## Quick Start

**Option A: Use the Setup Wizard (recommended)**

1. Open **your project** in Cursor (not this repo)
2. Switch to **Plan Mode** or **Agent Mode**
3. Paste the contents of [`SETUP-WIZARD.md`](./SETUP-WIZARD.md) into the chat
4. Answer a few questions about your stack
5. Done! The AI creates your `.cursor/rules/` folder automatically

> **Note:** The wizard must be run from inside your actual project directory, not from this repository.

> [!TIP]
> **Plan Mode** (recommended) — More structured. The AI analyzes your project, asks focused questions, shows you exactly what will be created, then executes after you confirm.

> [!TIP]
> **Agent Mode** — More conversational. The AI iterates with you and creates files on the fly. Good if you want to adjust things as you go.

<table>
<tr>
<td>

### 💎 Pro Tip

Use the best model you have access to. The wizard does a lot of thinking upfront so you don't have to correct it later. Five minutes with a good model now saves hours of fixes down the road.

</td>
</tr>
</table>

---

**Option B: Manual Setup**

1. Create `.cursor/rules/` in your project root
2. Copy the rules you need from the [`rules/`](./rules/) folder
3. Update the `globs` in each file to match your project structure

---

## Available Rules

### Frameworks

| Rule | Description |
|------|-------------|
| [`nextjs-15.mdc`](rules/frameworks/nextjs-15.mdc) | Next.js 15 App Router, Server Components, Server Actions |
| [`react-19.mdc`](rules/frameworks/react-19.mdc) | React 19 patterns, hooks, and best practices |
| [`vue-3.mdc`](rules/frameworks/vue-3.mdc) | Vue 3 Composition API and script setup |
| [`svelte-5.mdc`](rules/frameworks/svelte-5.mdc) | Svelte 5 runes and modern patterns |
| [`astro.mdc`](rules/frameworks/astro.mdc) | Astro components and island architecture |

### Languages

| Rule | Description |
|------|-------------|
| [`typescript.mdc`](rules/languages/typescript.mdc) | Strict TypeScript with modern type patterns |
| [`python.mdc`](rules/languages/python.mdc) | Python 3.12+ with type hints and async |
| [`go.mdc`](rules/languages/go.mdc) | Go idioms and error handling |

### Backends

| Rule | Description |
|------|-------------|
| [`supabase.mdc`](rules/backends/supabase.mdc) | Auth, RLS, Edge Functions, Realtime |
| [`fastapi.mdc`](rules/backends/fastapi.mdc) | FastAPI routes, Pydantic, async patterns |
| [`nodejs.mdc`](rules/backends/nodejs.mdc) | Node.js with Express/Fastify |

### Styling

| Rule | Description |
|------|-------------|
| [`tailwind.mdc`](rules/styling/tailwind.mdc) | Tailwind CSS v4 patterns and organization |
| [`shadcn-ui.mdc`](rules/styling/shadcn-ui.mdc) | shadcn/ui component patterns |

### Testing

| Rule | Description |
|------|-------------|
| [`vitest.mdc`](rules/testing/vitest.mdc) | Vitest with Testing Library |
| [`playwright.mdc`](rules/testing/playwright.mdc) | E2E testing with page objects |

### Best Practices

| Rule | Description |
|------|-------------|
| [`clean-code.mdc`](rules/best-practices/clean-code.mdc) | Naming, functions, DRY, SOLID |
| [`security.mdc`](rules/best-practices/security.mdc) | Auth patterns, secrets, validation |
| [`ai-security.mdc`](rules/best-practices/ai-security.mdc) | LLM security, prompt injection, PII filtering |
| [`accessibility.mdc`](rules/best-practices/accessibility.mdc) | ARIA, keyboard nav, screen readers |

### Stack Presets

These combine multiple rules for common technology combinations:

| Rule | Stack |
|------|-------|
| [`t3-stack.mdc`](rules/stacks/t3-stack.mdc) | Next.js + tRPC + Prisma + Tailwind |
| [`nextjs-supabase.mdc`](rules/stacks/nextjs-supabase.mdc) | Next.js + Supabase + shadcn/ui |
| [`mern-stack.mdc`](rules/stacks/mern-stack.mdc) | MongoDB + Express + React + Node.js |
| [`python-fastapi.mdc`](rules/stacks/python-fastapi.mdc) | FastAPI + PostgreSQL + SQLAlchemy |
| [`django-htmx.mdc`](rules/stacks/django-htmx.mdc) | Django + HTMX + Tailwind |

---

## How the Wizard Works

The Setup Wizard is a special prompt that turns Cursor into a project analyzer:

1. **Detection** - It reads your `package.json`, `tsconfig.json`, config files, etc.
2. **Questions** - Asks 4-6 questions to understand your preferences
3. **Planning** - Shows you exactly which rules will be created
4. **Execution** - Creates `.cursor/rules/` with customized rules

The wizard adapts to your project. Using Supabase? It includes those patterns. TypeScript strict mode? It adjusts accordingly. It's not a one-size-fits-all dump of rules.

---

## Rule

... (truncated)