.cursorrules (deprecated)

1# Next.js 14+ with TypeScript — Cursor Rules
2 
3You are an expert Next.js 14+ developer using TypeScript, the App Router, React Server Components, and Server Actions.
4 
5## Code Style
6 
7- Use TypeScript strict mode for all files. Never use `any` — prefer `unknown` with type narrowing.
8- Use named exports for components and functions. Default exports only for page.tsx, layout.tsx, loading.tsx, error.tsx, and not-found.tsx.
9- Prefer `const` arrow functions for components: `const MyComponent = () => { ... }`.
10- Use descriptive variable names: `isLoading`, `hasPermission`, `userList` — not `flag`, `data`, `arr`.
11- Import order: React/Next built-ins, third-party libraries, project aliases (@/), relative imports. Separate groups with blank lines.
12- Use `type` keyword for type-only imports: `import type { User } from '@/types'`.
13- Prefer `interface` for object shapes that may be extended. Use `type` for unions, intersections, and mapped types.
14- File naming: kebab-case for files and folders (`user-profile.tsx`). PascalCase for components in code.
15 
16## App Router Architecture
17 
18- Default to Server Components. Only add `'use client'` when the component needs interactivity (event handlers, useState, useEffect, browser APIs).
19- Keep `'use client'` boundaries as low in the component tree as possible. Extract interactive parts into small client components.
20- Use `page.tsx` for route pages, `layout.tsx` for shared layouts, `loading.tsx` for Suspense fallbacks, `error.tsx` for error boundaries.
21- Colocate related files: put components, utils, and types used by a single route inside that route's folder.
22- Use route groups `(group-name)` to organize routes without affecting the URL structure.
23- Use `generateMetadata` or `metadata` export for SEO on every page. Never skip metadata.
24 
25## Data Fetching
26 
27- Fetch data in Server Components using `async/await` directly — no useEffect for initial data loads.
28- Use `fetch()` with Next.js extended options for caching: `{ cache: 'force-cache' }` for static, `{ next: { revalidate: 3600 } }` for ISR, `{ cache: 'no-store' }` for dynamic.
29- Use Server Actions (`'use server'`) for mutations (form submissions, data updates). Define them in separate `actions.ts` files.
30- Validate all Server Action inputs with Zod schemas before processing.
31- Use `revalidatePath()` or `revalidateTag()` after mutations to update cached data.
32- Prefer parallel data fetching: `const [users, posts] = await Promise.all([getUsers(), getPosts()])`.
33 
34## React Server Components
35 
36- Never import or use hooks (useState, useEffect, etc.) in Server Components.
37- Never pass functions or event handlers as props from Server Components to Client Components.
38- Serialize data at the Server Component level — pass only plain objects and primitives to Client Components.
39- Use the `Suspense` boundary with `loading.tsx` or inline `<Suspense fallback={...}>` for streaming.
40- Prefer React Server Components for any component that doesn't need client-side interactivity.
41 
42## Error Handling
43 
44- Use `error.tsx` boundaries at route segment levels. Always provide a user-friendly message and a retry mechanism.
45- Wrap Server Action logic in try/catch blocks. Return structured results: `{ success: boolean, data?: T, error?: string }`.
46- Use `notFound()` from `next/navigation` to trigger 404 pages when a resource doesn't exist.
47- Log errors server-side with structured logging (include request context). Never expose stack traces to the client.
48 
49## Performance
50 
51- Use `next/image` for all images. Always provide `width`, `height`, and `alt` props. Use `priority` for above-the-fold images.
52- Use `next/font` for font loading — prefer `next/font/google` with `display: 'swap'`.
53- Use dynamic imports with `next/dynamic` for heavy client components that aren't needed on initial render.
54- Prefer CSS Modules or Tailwind CSS. Avoid runtime CSS-in-JS libraries in Server Components.
55- Use `generateStaticParams` for static generation of dynamic routes when the data set is known.
56- Minimize client-side JavaScript: fewer `'use client'` files = faster page loads.
57 
58## Testing
59 
60- Use Vitest for unit tests and React Testing Library for component tests.
61- Use Playwright for end-to-end tests. Place e2e tests in a top-level `e2e/` directory.
62- Test Server Actions by calling them directly with mock inputs.
63- Colocate unit tests with the code they test: `user-profile.test.tsx` next to `user-profile.tsx`.
64- Name test files with `.test.ts` or `.test.tsx` suffix.
65 
66## File Structure
67 
68```
69app/
70  (auth)/
71    login/page.tsx
72    register/page.tsx
73  (dashboard)/
74    layout.tsx
75    page.tsx
76    settings/page.tsx
77  api/
78    route.ts
79  layout.tsx
80  page.tsx
81  globals.css
82components/
83  ui/          — Reusable UI primitives (Button, Card, Modal)
84  features/    — Feature-specific components
85lib/
86  actions/     — Server Actions
87  db/          — Database client and queries
88  utils/       — Utility functions
89  validations/ — Zod schemas
90types/
91  index.ts     — Shared TypeScript types
92```
93 
94## Security
95 
96- Validate and sanitize all user inputs on the server (Server Actions, API routes).
97- Use `headers()` and `cookies()` from `next/headers` for auth checks in Server Components.
98- Never expose API keys or secrets in client components. Use server-only modules and environment variables.
99- Mark sensitive server-only modules with `import 'server-only'` to prevent accidental client imports.
100- Use CSRF protection for Server Actions (Next.js handles this by default with the same-origin check).
101- Set appropriate CSP headers via `next.config.js` `headers()` configuration.
102