React Router v7 Rules

tl;dr: pull react-router-v7.mdc from awesome-cursorrules before any app that uses React Router v7 framework mode. Models default to client-side fetching in useEffect, which double-renders and breaks progressive enhancement.

What it does

This rule set configures Cursor to treat route modules as the boundary for data loading, mutations, navigation state, and error handling in React Router v7. Without it, models reach for useEffect + fetch and lose the framework’s progressive enhancement story.

Sourced from PatrickJS/awesome-cursorrules — the community registry for .mdc Project Rules.

The rules

# React Router v7 Rules

## Route Modules

- Use route modules as the boundary for route UI, loader data, actions, metadata, and error boundaries.
- Keep route modules small; move shared UI to components and reusable data access to services.
- Prefer file-based routing in framework mode when the project is configured for it.
- Use nested routes for shared layouts and progressive disclosure.
- Export route-specific `ErrorBoundary` components for recoverable route failures.

## Data Loading

- Use loaders for route data that should be available before render.
- Keep loaders deterministic and side-effect free.
- Validate params and search params at the loader boundary.
- Return typed data and consume it through route hooks rather than duplicating fetch logic in components.
- Use deferred or streaming patterns only when they improve perceived performance.

## Mutations

- Use actions for route mutations and form submissions.
- Prefer `Form`, `useFetcher`, and `useSubmit` for progressive enhancement.
- Revalidate affected loader data after mutations.
- Handle validation errors as typed action data instead of generic exceptions.
- Keep server-only secrets and privileged operations out of client actions.

## Navigation and State

- Store shareable state in URL params or search params.
- Keep ephemeral UI state local to components.
- Use pending navigation state to show optimistic or loading UI.
- Avoid global state for data that belongs to route loaders.

## TypeScript and Testing

- Type loader and action return values.
- Add tests for route loaders, actions, validation failures, and error boundaries.
- Use integration tests for critical form and navigation flows.
- Mock network and persistence at the route-service boundary.

## Common Mistakes

- Do not duplicate loader fetches in `useEffect`.
- Do not mutate data in loaders.
- Do not hide route errors behind a single generic app-level catch-all.
- Do not put auth checks only in components when loader data is protected.

Installation

Drop the .mdc into .cursor/rules/ of your project:

mkdir -p .cursor/rules
curl -sL \
  https://raw.githubusercontent.com/PatrickJS/awesome-cursorrules/main/rules/react-router-v7.mdc \
  -o .cursor/rules/react-router-v7.mdc

Cursor picks up files in .cursor/rules/ automatically. No Cursor settings UI step needed for project-wide application.

Why it helps

Without framework-mode-aware rules, models will:

• Call fetch() inside useEffect instead of using a loader, breaking SSR and prefetch
• Forget to revalidate loader data after a mutation, leaving stale UI on screen
• Hide a single app-level ErrorBoundary instead of exporting one per route
• Put auth checks only in components, so protected loaders can still be hit server-side

These rules prevent the four most common framework-mode mistakes that cost debugging time.

Gotchas

• These are Cursor .mdc rules, not a Claude Code CLAUDE.md file. For Claude Code, paraphrase into your project’s CLAUDE.md.
• Framework mode is opt-in. If your project is on declarative mode, the loader/action rules don’t apply.

Related

• Next.js App Router Rules — concurrent opinionated-routing ruleset
• TanStack Query v5 Rules — pairs with React Router loaders via queryClient.ensureQueryData