react-router-v7

React Router v7 Framework Mode - Cursor Rules

🚨 CRITICAL: Route Type Imports - NEVER MAKE THIS MISTAKE

THE MOST IMPORTANT RULE: ALWAYS use ./+types/[routeName] for route type imports.

// ✅ CORRECT - ALWAYS use this pattern:
import type { Route } from "./+types/product-details";
import type { Route } from "./+types/product";
import type { Route } from "./+types/category";

// ❌ NEVER EVER use relative paths like this:
// import type { Route } from "../+types/product-details";  // WRONG!
// import type { Route } from "../../+types/product";       // WRONG!

If you see TypeScript errors about missing ./+types/[routeName] modules:

1. IMMEDIATELY run typecheck to generate the types
2. Or start the dev server which will auto-generate types
3. NEVER try to "fix" it by changing the import path

Type Generation & Workflow

• Run typecheck after adding/renaming any routes
• Run typecheck if you see missing type errors
• Types are auto-generated by @react-router/dev in ./+types/[routeName] relative to each route file
• The dev server will also generate types automatically

---

Critical Package Guidelines

✅ CORRECT Packages:

• react-router - Main package for routing components and hooks
• @react-router/dev - Development tools and route configuration
• @react-router/node - Node.js server adapter
• @react-router/serve - Production server

❌ NEVER Use:

• react-router-dom - Legacy package, use react-router instead
• @remix-run/* - Old packages, replaced by @react-router/*
• React Router v6 patterns - Completely different architecture

Essential Framework Architecture

Route Configuration (app/routes.ts)

import { type RouteConfig, index, route } from "@react-router/dev/routes";

export default [
  index("routes/home.tsx"),
  route("about", "routes/about.tsx"),
  route("products/:id", "routes/product.tsx", [
    index("routes/product-overview.tsx"),
    route("reviews", "routes/product-reviews.tsx"),
  ]),
  route("categories", "routes/categories-layout.tsx", [
    index("routes/categories-list.tsx"),
    route(":slug", "routes/category-details.tsx"),
  ]),
] satisfies RouteConfig;