Cursor Rules for React: .mdc Rule Set From Your Own Repo

Prompt

Act as a senior React and TypeScript engineer who writes Cursor project rules (.mdc files in .cursor/rules) for React codebases, so Cursor's Agent follows this repo's real patterns instead of generic React habits.

Inputs:
- package.json dependencies and scripts, pasted as is: [PackageJson]
- Folder structure of src/ two levels deep: [FolderTree]
- tsconfig.json strictness settings and the lint config in use: [TsconfigAndLint]
- Styling approach and state or data fetching libraries actually used: [StylingAndState]
- Test runner, test library, and where tests live: [TestingSetup]
- Team conventions that are not written down yet: [TeamConventions]
- Mistakes the agent keeps making in this repo: [AgentMistakes]

Generate:
1. Evidence check: every library, script, and folder you will mention in the rules, with where it came from (PackageJson, FolderTree, TsconfigAndLint, or my notes). Anything you cannot find stays out of the rules.
2. A rule plan table of 4 to 6 .mdc files: file name, Cursor rule type (Always Apply, Apply to Specific Files, Apply Intelligently, or Apply Manually), the globs or description that trigger it, and a one line purpose. Keep only one Always Apply rule.
3. The Always Apply core rule, under 30 lines: what the app is, the folder map from FolderTree, and the exact scripts from PackageJson to run after edits (lint, type check, tests).
4. A components rule scoped with globs to the component folders: export style, props typing, file naming, and where logic goes, from TeamConventions.
5. A data fetching and state rule for the exact libraries in StylingAndState: where queries or stores live, loading and error states, and what never goes in a component.
6. A testing rule scoped to test files using TestingSetup: query style, what to mock, and the command to run one file.
7. An Apply Intelligently rule (description only) for one task that comes up often in TeamConventions or AgentMistakes.
8. Each item in AgentMistakes as a short do and do not pair, placed in the rule where it belongs.
9. Full contents of every .mdc file with front matter (description, globs, alwaysApply), ready to save.

Constraints:
- Mention only packages present in PackageJson and paths present in FolderTree.
- Short, specific rules; no generic React tutorials and no style guide the linter already enforces.
- Do not change the React version or suggest new libraries.

Instructions

Run this in Cursor's Agent chat with package.json, tsconfig.json, and your lint config attached or pasted. Replace every [bracket]. Save each generated block as its own .mdc file in .cursor/rules, then check each rule's type under Customize, Rules in Cursor and test it on a real task. A single .cursorrules file in the project root is the legacy format; use .cursor/rules/*.mdc instead.

Generated Output

This image was generated using the prompt above.

Cursor Rules for React: .mdc Rule Set From Your Own Repo - Result

Examples

Example Input

PackageJson: dependencies: react 18.3, react-dom 18.3, react-router-dom 6, @tanstack/react-query 5, react-hook-form 7, zod 3, @hookform/resolvers, clsx. devDependencies: typescript 5, vite 5, vitest 2, @testing-library/react, @testing-library/user-event, msw 2, eslint 9, tailwindcss 3. scripts: dev, build, lint ("eslint ."), typecheck ("tsc --noEmit"), test ("vitest run").
FolderTree: src/app/ (router.tsx, providers.tsx), src/features/billing/{api,components,hooks}, src/features/projects/{api,components,hooks}, src/components/ui/, src/lib/ (http.ts, query-client.ts), src/test/ (setup.ts, handlers.ts).
TsconfigAndLint: strict true, noUncheckedIndexedAccess true. eslint flat config with react-hooks plugin.
StylingAndState: Tailwind with clsx. Server state only through TanStack Query hooks in each feature's hooks/ folder. Forms with react-hook-form and zod schemas. No global store.
TestingSetup: Vitest plus Testing Library, MSW handlers in src/test/handlers.ts, tests next to the file as Name.test.tsx.
TeamConventions: Named exports only. One component per file, PascalCase file names. API calls only in feature api/ files through src/lib/http.ts.
AgentMistakes: Fetches data in useEffect. Adds default exports. Uses any to silence type errors. Calls fetch directly inside components.

Example Output

1. EVIDENCE
Libraries: react 18.3, react-router-dom 6, @tanstack/react-query 5, react-hook-form 7, zod 3, @hookform/resolvers, clsx, tailwindcss 3, vitest 2, Testing Library, msw 2 (PackageJson). Scripts: lint, typecheck, test (PackageJson). Folders: src/app, src/features/*/{api,components,hooks}, src/components/ui, src/lib, src/test (FolderTree). Strict mode and noUncheckedIndexedAccess (TsconfigAndLint). Export and file rules (TeamConventions).

2. RULE PLAN
| File | Type | Trigger | Purpose |
| core.mdc | Always Apply | | Map and commands |
| components.mdc | Apply to Specific Files | src/features/**/components/**/*.tsx, src/components/ui/**/*.tsx | Component rules |
| data.mdc | Apply to Specific Files | src/features/**/api/**, src/features/**/hooks/**, src/lib/** | Query and API rules |
| testing.mdc | Apply to Specific Files | **/*.test.tsx, src/test/** | Vitest and MSW |
| forms.mdc | Apply Intelligently | description: building or changing a form | react-hook-form and zod |

3. core.mdc
---
description: Project map and commands
alwaysApply: true
---
- React 18 + TypeScript (strict) app built with Vite.
- Routes in src/app/router.tsx, providers in src/app/providers.tsx.
- Features live in src/features/{feature}/ with api/, components/, hooks/.
- Shared UI in src/components/ui/. HTTP client in src/lib/http.ts.
- After edits run: npm run lint, npm run typecheck, npm run test.
- Never use any. Fix the type or narrow it.

4. components.mdc
---
globs: src/features/**/components/**/*.tsx, src/components/ui/**/*.tsx
alwaysApply: false
---
- Named exports only. One component per file, PascalCase file name.
- Type props with an interface named [Component]Props.
- Style with Tailwind classes; combine conditional classes with clsx.
- No fetch, no http.ts imports, no useEffect for loading data. Use the feature's hooks.

5. data.mdc
---
globs: src/features/**/api/**, src/features/**/hooks/**, src/lib/**
alwaysApply: false
---
- API functions live in the feature's api/ folder and call src/lib/http.ts.
- Wrap every API call in a TanStack Query hook in hooks/ (useQuery for reads, useMutation for writes) and invalidate the related query keys after a mutation.
- Return loading and error states to the component; do not swallow errors.
- No global store; server state stays in TanStack Query.

6. testing.mdc
---
globs: **/*.test.tsx, src/test/**
alwaysApply: false
---
- Tests sit next to the file as Name.test.tsx.
- Query by role and label with Testing Library; use user-event for input.
- Mock the network with MSW handlers in src/test/handlers.ts, never by mocking fetch.
- Run one file: npx vitest run path/to/Name.test.tsx.

7. forms.mdc
---
description: Use when building or changing a form
alwaysApply: false
---
- Define a zod schema first and infer the form type from it.
- Use react-hook-form with zodResolver from @hookform/resolvers.
- Submit through a useMutation hook from the feature's hooks/.

8. AGENT MISTAKES
Do: load data with a Query hook. Do not: fetch in useEffect (components.mdc, data.mdc).
Do: named exports. Do not: default exports (components.mdc).
Do: fix or narrow the type. Do not: use any (core.mdc).
Do: call APIs in api/ through http.ts. Do not: call fetch in a component (components.mdc).

9. Save each block as .cursor/rules/[file].mdc and check each rule's type under Customize, Rules.