.cursorrules (deprecated)

1# Next.js 14+ App Router — Cursor Rules
2# Senior-level patterns for production Next.js applications
3 
4# Project Context
5You are working on a Next.js 14+ application using the App Router (app/ directory).
6All components are React Server Components by default unless explicitly marked with "use client".
7The project uses TypeScript, Tailwind CSS, and follows the latest Next.js conventions.
8 
9# Architecture Rules
10- Use the app/ directory exclusively. Never create pages/ directory files.
11- Colocate related files: page.tsx, layout.tsx, loading.tsx, error.tsx, not-found.tsx in the same route folder.
12- Keep route groups (parentheses folders) for logical organization without affecting URL structure.
13- Use parallel routes (@folder) and intercepting routes ((..)folder) when building modal patterns or dashboards.
14 
15# Server Components (Default)
16- Every component is a Server Component unless it needs interactivity or browser APIs.
17- DO: Fetch data directly in Server Components using async/await.
18- DO: Use `fetch()` with Next.js caching options: `{ cache: 'force-cache' }`, `{ next: { revalidate: 3600 } }`.
19- DON'T: Import useState, useEffect, useRef, or event handlers in Server Components.
20- DON'T: Pass functions as props from Server Components to Client Components.
21 
22# Client Components
23- Mark with "use client" directive at the top of the file.
24- Keep Client Components as small and leaf-level as possible.
25- DO: Extract interactive parts into small Client Components, keep the parent as a Server Component.
26- DON'T: Mark a layout.tsx as "use client" — this forces the entire subtree to be client-rendered.
27 
28# Server Actions
29- Define server actions in separate files with "use server" at the top.
30- Place in app/actions/ or colocate with the feature: app/dashboard/actions.ts.
31- Always validate input with zod before processing.
32- Return typed response objects: `{ success: boolean; data?: T; error?: string }`.
33- Use `revalidatePath()` or `revalidateTag()` after mutations, never `router.refresh()`.
34 
35# Data Fetching Patterns
36- Fetch data in the component that needs it — Next.js deduplicates fetch requests automatically.
37- Use `generateStaticParams()` for dynamic routes that should be statically generated.
38- Implement proper loading states with loading.tsx Suspense boundaries.
39- Use `unstable_cache()` for non-fetch data sources (database queries, API calls via SDK).
40 
41# Error Handling
42- Create error.tsx files at each route segment that might fail.
43- error.tsx must be a Client Component (it receives error and reset props).
44- Use not-found.tsx for 404 states, call `notFound()` from Server Components.
45- Wrap external API calls in try/catch with meaningful error messages.
46 
47# Metadata & SEO
48- Export `metadata` object or `generateMetadata()` function from page.tsx and layout.tsx.
49- Use `generateMetadata()` for dynamic pages that need data-driven titles/descriptions.
50- Always include: title, description, openGraph, and twitter card metadata.
51- Place opengraph-image.tsx in route folders for dynamic OG images.
52 
53# File Naming Conventions
54- Components: PascalCase (UserProfile.tsx)
55- Utilities/helpers: camelCase (formatDate.ts)
56- Route files: lowercase (page.tsx, layout.tsx, loading.tsx, error.tsx)
57- Server actions: camelCase verb prefix (createUser.ts, updateProfile.ts)
58- Types: PascalCase with .types.ts suffix (User.types.ts)
59 
60# Performance
61- Use `<Image>` component from next/image for all images — never raw <img> tags.
62- Use `<Link>` component from next/link for all internal navigation.
63- Implement `<Suspense>` boundaries around slow-loading components.
64- Use `dynamic()` import with `{ ssr: false }` for heavy client-only libraries.
65- Prefer CSS Modules or Tailwind over CSS-in-JS (no runtime cost).
66 
67# TypeScript Patterns
68- Define route params types: `{ params: { slug: string } }` for page components.
69- Use `SearchParams` type for page components that read query strings.
70- Type server action return values explicitly.
71- Use `satisfies` operator for metadata objects to get autocomplete while keeping literal types.
72 
73# Testing
74- Use @testing-library/react for component tests.
75- Test Server Components by importing and rendering them directly (they're just async functions).
76- Mock fetch calls and database queries in tests.
77- Use Playwright for E2E tests against the dev server.
78 
79# Common Mistakes to Avoid
80- DON'T use `useRouter` for navigation in Server Components — use `redirect()` instead.
81- DON'T store server-only secrets in components — use environment variables with NEXT_PUBLIC_ prefix only for client-side values.
82- DON'T use `getServerSideProps` or `getStaticProps` — these are Pages Router patterns.
83- DON'T create API routes (route.ts) just to fetch data for your own pages — fetch directly in Server Components.
84- DON'T put "use client" on every component — think about the boundary carefully.
85