Cursor Rules for Next.js: Project-Specific AI Guidance

touch .cursorrules

# Next.js 15 — App Router — Cursor Rules
# Stack: Next.js 15, React 19, TypeScript 5 strict, Tailwind CSS 4, Drizzle ORM

## Core Framework Rules

- Use the App Router exclusively. Never suggest Pages Router (`pages/` directory, `getServerSideProps`, `getStaticProps`, `_app.tsx`).
- Default to React Server Components (RSC). Only add `"use client"` when the component uses browser APIs, event handlers, or React hooks.
- For data fetching: fetch directly in async Server Components. Do not use `useEffect` + `useState` for data that can be fetched server-side.
- Use `next/navigation` for routing hooks: `useRouter`, `usePathname`, `useSearchParams`. Never import from `next/router`.
- Server Actions require `"use server"` at the top of the file or function. Use them for form submissions and data mutations.
- Use `<Link href="">` from `next/link` for internal navigation. Never use `<a>` tags for internal routes.

## TypeScript Rules

- Strict mode is enabled. Never use `any`. Use `unknown` and narrow with guards.
- Use `type` for object shapes and unions. Use `interface` only when extending.
- All component props must be explicitly typed. No implicit prop types.
- Use `satisfies` operator to validate object literals against types without widening.
- React component return type: let TypeScript infer it. Do not manually annotate `JSX.Element` or `React.FC`.

## File and Folder Conventions

- Components: `PascalCase.tsx` — e.g., `UserCard.tsx`
- Pages and layouts: `lowercase` — `page.tsx`, `layout.tsx`, `loading.tsx`, `error.tsx`
- Utilities and hooks: `camelCase.ts` — e.g., `formatDate.ts`, `useTheme.ts`
- Server Actions: `actions.ts` inside the relevant feature folder
- Co-locate components with their route: `/app/dashboard/UserCard.tsx`
- Shared UI: `/components/ui/` — atomic, no business logic
- Feature components: `/components/features/` — business logic allowed

## Styling Rules

- Use Tailwind CSS utility classes. No inline styles, no CSS modules unless specifically asked.
- Responsive design: mobile-first. Start with base styles, add `md:` and `lg:` breakpoints.
- Dynamic classes: use `clsx` or `cn` (shadcn helper). Never string-concatenate class names.
- Do not use arbitrary values (e.g., `w-[347px]`) unless no standard value fits. Prefer the design scale.

## Data Fetching Patterns

- Use `fetch()` with Next.js cache options in Server Components: `{ cache: 'force-cache' }`, `{ next: { revalidate: 60 } }`, or `{ cache: 'no-store' }`.
- Parallel data fetching: use `Promise.all()` for independent fetches — never await sequentially.
- Database queries: use Drizzle ORM. Raw SQL only for complex queries Drizzle can't express.
- Wrap database calls in try/catch. Return typed result objects, not thrown errors, to the UI layer.

## Error Handling

- Use `error.tsx` files for route-level error boundaries.
- Use `notFound()` from `next/navigation` for 404 cases — do not throw manually.
- Server Actions return `{ success: boolean; error?: string }`. Never throw from a Server Action called by a form.

## Performance

- Images: always use `<Image>` from `next/image`. Set explicit `width` and `height` or use `fill` with a sized container.
- Fonts: load via `next/font`. Never import fonts from Google Fonts CDN directly.
- Heavy client components: wrap in `dynamic(() => import(...), { ssr: false })` when they are not needed on initial render.
- Keep Client Component boundaries as deep as possible in the tree.

## Code Style

- No default exports except for Next.js special files (`page.tsx`, `layout.tsx`, `error.tsx`, `loading.tsx`). Use named exports for everything else.
- Async Server Components: declare as `async function ComponentName()`.
- Short functions over long ones. Extract logic into clearly named utilities.
- Comments explain WHY, not WHAT. Skip obvious comments.

## Auth

- Auth provider: Clerk. Import from `@clerk/nextjs`.
- Protect server-side routes with `auth()` from `@clerk/nextjs/server`.
- For client-side user data: use `useUser()` hook. Never pass the full user object as a prop through multiple layers.
- Auth middleware is in `middleware.ts` at project root. Do not duplicate auth checks in layouts.

## UI Components

- Use shadcn/ui components from `/components/ui/`. Do not rebuild primitives like Button, Dialog, or Input from scratch.
- Extend shadcn components via the `className` prop and `cn()`. Do not modify the source files in `/components/ui/` directly.
- Form validation: use `react-hook-form` with `zod` resolver. The schema lives next to the form file.

## API Route Handlers

- Route handlers live in `/app/api/[resource]/route.ts`.
- Always type the return value: `return NextResponse.json<ResponseType>(data)`.
- Validate request bodies with Zod before processing. Return 400 on validation failure.
- Use HTTP status codes correctly: 200 success, 201 created, 400 bad request, 401 unauthenticated, 403 forbidden, 404 not found, 500 server error.

git add .cursorrules
git commit -m "chore: add Cursor rules for Next.js 15 App Router"

# Root-level rules (applies everywhere)
.cursorrules

# App-specific rules (applies only inside /apps/web)
apps/web/.cursorrules

# Package-specific rules
packages/ui/.cursorrules