# Best Cursor Rules for Next.js and SaaS in 2026 (.mdc Examples You Can Copy)

> 10 copy-paste Cursor .mdc rules for Next.js, Supabase, Stripe, Tailwind and TypeScript, with frontmatter, rationale, and which rules to turn into skills.

Canonical: https://www.agentickit.co/blog/best-cursor-rules-2026
Last updated: 2026-10-25

**Short answer:** the best Cursor rules for a solo SaaS are ten small `.mdc` files in `.cursor/rules/`, each under 50 lines and scoped with a `globs` pattern so it only loads when the agent touches matching files. Below are the ten I would install first for a Next.js App Router, Supabase, Stripe, Tailwind and TypeScript stack, each copy-paste ready with a short rationale, plus which of them should become skills instead.

If you want the philosophy behind a rules stack (activation modes, the always-on core, multi-tenant examples), read [Cursor Rules for SaaS Founders](/blog/cursor-rules-saas-founders). This post is the other half: the files themselves. For more stacks in shorter, faster-to-copy form, see [Cursor Rules Generator Prompts: 15 Copy-Paste Examples for 2026](/blog/cursor-rules-generator-prompts).

## Rules in 2026: .mdc, the four apply modes, and why .cursorrules is legacy

Project rules live in `.cursor/rules/` as `.mdc` files: markdown with a small frontmatter block. Three frontmatter fields matter:

- `description`: one line saying what the rule is for. The agent reads it to decide whether to pull the rule in.
- `globs`: file patterns such as `app/api/**/*.ts`. When the agent works on a matching file, the rule loads.
- `alwaysApply`: `true` puts the rule in every prompt.

Those fields give you the four apply modes described in [Cursor's rules docs](https://cursor.com/docs/rules): always apply, apply intelligently (the agent decides from the description), apply to specific files (glob match), and apply manually (you `@`-mention it). Cursor renames things often, so check the docs if a label has shifted.

**On `.cursorrules`:** the single root-level `.cursorrules` file is the older format. It is a Cursor-only convention: other tools do not read it, it cannot be scoped by file, and it is one block of text that loads whether relevant or not. It still works in many setups, but I treat it as legacy and would not start a new project with it. If you have one, split it into `.mdc` files. The [Config Converter](/tools/config-converter) can move files between editor formats.

If you'd rather generate the ten files below than hand-write them, see [13 Best Free Cursor Tools in 2026](/blog/free-cursor-tools-2026) for a ranked list of generators, graders and converters, including which ones actually tailor output to your stack versus just giving you a template.

## Quality bar: what separates a rule from noise

Community collections are a fine source of ideas, but quality varies a lot. The popular `awesome-cursorrules` repo is a pile of contributed files: some are sharp, many are a language-and-framework wishlist ("write clean code, follow best practices") that tells the agent nothing it was not already doing. I did not audit the repo file by file, so treat that as a warning to read before you copy, not a ranking.

My filter for every rule below:

1. **Under 50 lines.** If it needs more, it is a skill (see the migration section).
2. **Glob-scoped.** Only `alwaysApply: true` if it would be wrong to ever skip it.
3. **Testable.** A reviewer can look at a diff and say "this violated rule 3." "Write maintainable code" fails; "never read `process.env` outside `lib/env.ts`" passes.
4. **No linter overlap.** If ESLint or TypeScript can enforce it, enforce it there. Rules cost tokens on every matching turn.
5. **A bad and good example** where the mistake is subtle.

## The 10 rules

Adjust paths to your layout. All assume `app/` at the repo root and a `lib/` folder.

### 1. Next.js App Router

```md
---
description: Next.js App Router conventions for pages, layouts and components
globs: app/**/*.tsx
alwaysApply: false
---
- Components are Server Components by default. Add "use client" only for state, effects, or browser APIs, and push it to the smallest leaf component.
- Fetch data in Server Components or route handlers, never in useEffect.
- Every route segment that loads data gets a loading.tsx and an error.tsx.
- Use next/link and next/image. No raw <a> for internal links, no raw <img>.
- Metadata goes in generateMetadata or the metadata export, never a hand-written <head>.
- Do not import server-only modules (db client, secrets) into a file marked "use client".
```

**Why:** the most common agent mistake in App Router is sprinkling `"use client"` at the top of everything until the error goes away. One line fixing the default saves bundle size and leaked server code.

### 2. Server actions

```md
---
description: Rules for Next.js server actions and form mutations
globs: app/**/actions.ts,app/**/*actions*.ts
alwaysApply: false
---
- Every server action starts with "use server" and re-checks the session. Never trust that the UI hid the button.
- Validate input with a zod schema before touching the database. Never pass FormData straight to a query.
- Take the user and tenant id from the session, never from the arguments.
- Return { ok: true, data } or { ok: false, error } instead of throwing for expected failures.
- Call revalidatePath or revalidateTag after a successful mutation.
```

**Why:** a server action is a public HTTP endpoint wearing a function costume. Agents treat it like an internal helper. This rule keeps auth and validation attached to it.

### 3. Supabase and Postgres RLS

```md
---
description: Supabase queries, migrations and row level security
globs: supabase/**/*.sql,lib/db/**/*.ts
alwaysApply: false
---
- Every new table gets "enable row level security" in the same migration that creates it.
- Every table with user data has a policy tied to auth.uid() or the tenant id. No "using (true)" policies.
- The service-role key is server-only. Never import it in a file that can reach the browser.
- Migrations are new timestamped files. Never edit an applied migration.
- Add an index for every foreign key and every column used in a policy.
- Select explicit columns. No select("*") in app code.
```

**Why:** RLS is where solo-built SaaS apps quietly leak data. A table created without RLS enabled is open to anyone holding the public client key. Making "enable RLS in the same migration" a rule removes the forgettable step.

### 4. Stripe webhooks

```md
---
description: Stripe webhook handlers and billing state
globs: app/api/stripe/**/*.ts,app/api/webhooks/**/*.ts,lib/stripe/**/*.ts
alwaysApply: false
---
- Read the raw body with request.text() and verify the signature with stripe.webhooks.constructEvent before parsing anything.
- Handlers must be idempotent. Store the event id and skip events already processed.
- Return 200 quickly. Do slow work after recording the event.
- Treat the webhook, not the checkout success redirect, as the source of truth for subscription status.
- Never log full event payloads or card data.
- Pin the Stripe API version in one place (lib/stripe/client.ts).
```

**Why:** Stripe can deliver an event more than once, and a success page can be skipped by a closed tab. These lines are the difference between "paid users sometimes have no access" and a billing state you can trust. For the full four-rule set split by glob (signature verification, idempotency, subscription state, secret hygiene), see [Cursor rules for Stripe & billing codebases](/compare/cursor-rules-for-stripe). If you're setting the same thing up in Claude Code instead, see the [Claude Code Stripe webhooks setup guide](/blog/claude-code-stripe-webhooks-setup) for the SKILL.md version.

### 5. Tailwind

```md
---
description: Tailwind styling conventions
globs: **/*.tsx,**/*.css
alwaysApply: false
---
- Use Tailwind utilities and the design tokens in the Tailwind config. No inline style props except for dynamic values.
- No arbitrary colors like text-[#3b82f6]. Use a token.
- Merge conditional classes with the cn() helper, not string concatenation.
- Mobile first: base classes for small screens, md:/lg: for larger.
- Extract a component after the third repeat of the same class list, not a custom CSS class.
```

**Why:** without this, every generated component invents its own blue. One token rule keeps a solo-built UI consistent.

### 6. TypeScript strictness

```md
---
description: TypeScript type safety rules
globs: **/*.ts,**/*.tsx
alwaysApply: false
---
- No `any`. Use `unknown` and narrow it, or write the type.
- No non-null assertions (!) on values that come from outside the program.
- Validate external data (API bodies, env, webhooks) with zod and infer the type from the schema.
- Prefer discriminated unions over optional-field soup.
- Do not silence errors with @ts-ignore. Use @ts-expect-error with a reason if unavoidable.
```

**Why:** `strict: true` in `tsconfig` catches a lot, but agents reach for `any` the moment a type is awkward. Naming the escape hatches closes them. Keep the compiler flags as the enforcement; the rule is the nudge.

### 7. API errors

```md
---
description: Error shape and status codes for API routes
globs: app/api/**/*.ts
alwaysApply: false
---
- Every route returns errors as { error: { code, message } } with the correct HTTP status.
- 400 invalid input, 401 unauthenticated, 403 unauthorized, 404 missing, 409 conflict, 429 rate limited.
- Never return err.message, stack traces, or SQL errors to the client. Log them server-side.
- Parse the body with zod; on failure return 400 with field-level messages.
- Wrap handlers so unexpected throws become a generic 500 and are logged with a request id.
```

**Why:** this is the rule that stops the leaky `{ error: err.message }` response. One consistent shape also makes your frontend error handling a single function.

### 8. Testing

```md
---
description: Test conventions with Vitest and Playwright
globs: **/*.test.ts,**/*.test.tsx,e2e/**/*.ts
alwaysApply: false
---
- Test behavior through public functions, not implementation details.
- One behavior per test, named "does X when Y".
- Do not mock the database for RLS or billing logic. Use a local test database.
- Mock only network boundaries (Stripe, email). Never mock the unit under test.
- Every bug fix ships with a test that failed before the fix.
- e2e tests cover signup, checkout and the one core action. Not every page.
```

**Why:** agents love writing tests that mock everything and assert the mock was called. This rule points tests at behavior. Swap Vitest and Playwright for your own runners.

### 9. Env and secrets

```md
---
description: Environment variables and secrets handling
globs: **/*.ts,**/*.tsx,.env*
alwaysApply: true
---
- Read environment variables only through lib/env.ts, which validates them with zod at startup.
- Only variables prefixed NEXT_PUBLIC_ may reach client code, and they must be safe to publish.
- Never hardcode keys, tokens or connection strings. Never print them in logs.
- Never create or edit .env files with real values. Add the name to .env.example instead.
- If a secret appears in a diff or chat, stop and tell me to rotate it.
```

**Why:** this one is `alwaysApply: true` on purpose: a leaked key is the failure you cannot undo by reverting a commit. If you add only one rule from this list, make it this one, and read [the API key leak check](/blog/vibe-coding-exposed-api-keys).

### 10. Git hygiene

```md
---
description: Commit and branch conventions
alwaysApply: true
---
- Never commit directly to main. Work on a branch.
- Commit messages: imperative, under 72 characters on the first line, say why.
- One logical change per commit. Do not mix refactors with features.
- Never run git push --force, git reset --hard, or delete branches without asking.
- Do not commit generated files, .env files, or build output.
```

**Why:** it is short, always relevant, and it stops two classic agent accidents: pushing to the wrong branch and rewriting history.

## Summary table

| # | Rule | Scope | Mode | Skill instead? |
| --- | --- | --- | --- | --- |
| 1 | Next.js App Router | `app/**/*.tsx` | Glob | Keep |
| 2 | Server actions | `**/actions.ts` | Glob | Keep |
| 3 | Supabase RLS | `supabase/**`, `lib/db/**` | Glob | Keep the bans, move the policy cookbook to a skill |
| 4 | Stripe webhooks | `app/api/stripe/**` | Glob | Keep the bans, move the event-by-event guide to a skill |
| 5 | Tailwind | `**/*.tsx` | Glob | Keep |
| 6 | TypeScript | `**/*.ts(x)` | Glob | Keep (the compiler enforces the rest) |
| 7 | API errors | `app/api/**` | Glob | Keep the bans, move the status-code table to a skill |
| 8 | Testing | test files | Glob | Skill if you add long recipes |
| 9 | Env and secrets | everywhere | Always | Keep |
| 10 | Git hygiene | none | Always | Keep |

## Which rules should become skills

A rule is for short, always-correct constraints that attach to files. A skill is a longer playbook the agent loads when the task matches. My test: **if a rule file is heading past 50 lines, or it explains how to do something rather than what never to do, it is a skill.**

In the list above the pattern repeats three times: keep the five-line ban as a rule, and move the cookbook (RLS policy patterns, Stripe event handling, the full error-code table) into a skill the agent reads on demand. That keeps per-turn context small. The [Rules vs Skills comparison](/compare/cursor-rules-vs-skills) lays out the trade-offs, and [Best Cursor Skills in 2026](/blog/best-cursor-skills) has copy-paste skills to start from.

Want to pair these rules with the commands that should assume them — like `/db-migration` assuming the migration-safety rule, or `/security-pass` assuming the auth rule? See [25 Cursor Slash Commands and Rules Combos](/blog/cursor-slash-commands-rules-combos).

Cursor has a `/migrate-to-skills` command aimed at converting existing rules into skills. I have not verified exactly which rules it converts in your Cursor version, so run it on a branch and review the diff: check that descriptions still say *when* to trigger, and that anything you need on every turn stayed a rule.

## Grade your own rules

Before you add ten files, find out how good the ones you have are. The free [Rules File Grader](/tools/rules-grader) takes a `.mdc` or `.cursorrules` file so you can see what is vague or untestable. Run your current file through it, fix what it flags, then add rules from this list one at a time.

## How to roll these out without breaking your workflow

1. Create `.cursor/rules/` and add rules 9 and 10 first. They are always-on and low risk.
2. Add the glob-scoped rule for the code you touch most this week (usually one or two).
3. Watch what the agent does. When it repeats a mistake, write an eight-line rule for that mistake instead of lengthening an existing file.
4. Delete a rule if a few weeks pass and the agent never needed it.
5. Commit the folder. Rules are code-review material, and they travel with the repo.

## FAQ

**What is the difference between .mdc and .cursorrules?** `.mdc` files live in `.cursor/rules/` and carry frontmatter (`description`, `globs`, `alwaysApply`) so they can be scoped. `.cursorrules` is a single legacy file that only Cursor reads and cannot be scoped.

**How long should a Cursor rule be?** Under 50 lines is my bar. Cursor's own docs recommend keeping rules focused and splitting large ones. Anything that grows beyond that is usually a skill.

**Should every rule be alwaysApply?** No. Reserve it for constraints that are never safe to skip, like secrets handling. Glob-scope everything else so rules only load when relevant.

**Can I copy rules from community collections like awesome-cursorrules?** Yes, as inspiration, but read each one first. Quality varies, and many are generic style advice. Trim them to testable lines and scope them with globs.

**Do these rules work in Claude Code?** Claude Code reads `CLAUDE.md` and `.claude/` files, not `.cursor/rules/`. AgenticKit installs equivalents for both, and the Config Converter can translate a file.

## Drop-in AgenticKit install

If you would rather not hand-write all of this, AgenticKit installs 34 agents, 61 skills and 47 commands, including conventions, API patterns and error-handling skills, with one command:

```bash
npx agentickit-cursor init --target cursor
```

Browse the [skills](/skills), try the [free tools](/tools), or see [pricing](/pricing).

## Sources

- [Cursor docs: Rules](https://cursor.com/docs/rules), referenced for rule locations, frontmatter and apply modes. I did not re-fetch it on 2026-10-25, so confirm current labels there.


## Related
- [rules-grader](https://www.agentickit.co/tools/rules-grader)
- [config-converter](https://www.agentickit.co/tools/config-converter)
- [tech-lead](https://www.agentickit.co/agents/tech-lead)
- [api-engineer](https://www.agentickit.co/agents/api-engineer)
- [security-auditor](https://www.agentickit.co/agents/security-auditor)
- [project-conventions](https://www.agentickit.co/skills/project-conventions)
- [api-patterns](https://www.agentickit.co/skills/api-patterns)
- [error-handling](https://www.agentickit.co/skills/error-handling)
- [/audit](https://www.agentickit.co/commands/audit)
- [/ship](https://www.agentickit.co/commands/ship)
