cursorrules

You are working on nextjs-app.

Tech stack: Next.js (App Router), TypeScript, Tailwind CSS, Drizzle ORM, postgres, Vitest + playwright + testing-library, ESLint + Prettier, pnpm, Vercel, NextAuth.js, tRPC

Rules:

• Use the app/ directory; every route folder needs a page.tsx to be publicly accessible
• Add 'use client' at the top of a file only when the component needs interactivity, browser APIs, hooks (useState, useEffect), or event handlers
• Never import a Server Component into a Client Component — pass it as children instead
• Use fetch() with Next.js extended options: { cache: 'force-cache' } (default, static), { cache: 'no-store' } (dynamic), or { next: { revalidate: N } } for ISR
• Use utility classes directly in markup — avoid writing custom CSS unless absolutely necessary
• Never use @apply in component styles — it defeats the purpose of utility-first CSS and increases bundle size
• Dark mode: use dark: variant; configure strategy (class or media) as needed
• Use design tokens from the theme for consistency — avoid arbitrary values like w-[137px] unless truly one-off
• Use the dialect-specific column builders: pgTable, mysqlTable, or sqliteTable
• Use $inferSelect and $inferInsert to derive TypeScript types from table definitions — never manually duplicate types
• Use the query builder API (db.select().from(users).where(eq(users.id, id))) for most operations
• Use the relational query API (db.query.users.findMany({ with: { posts: true } })) for nested/related data
• Use publicProcedure for unauthenticated endpoints; create protectedProcedure with auth middleware for authenticated ones
• Use .query() for read operations (GET-like); .mutation() for write operations (POST/PUT/DELETE-like)
• Use .subscription() for real-time WebSocket-based data streams
• Use middleware (.use()) for cross-cutting concerns: auth checks, logging, rate limiting
• Use useSession() hook in Client Components for session data and status
• Use getServerSession(authOptions) in getServerSideProps or API routes for server-side session checks
• Use callbacks.jwt to enrich the JWT token with custom claims (role, userId)
• Use callbacks.session to expose token data to the client session object
• Use describe() to group related tests; it() or test() for individual cases
• Use expect() assertions — prefer specific matchers (toEqual, toContain, toThrow) over generic toBeTruthy
• Use vi.mock('module') at the top of the file to mock entire modules — it is hoisted automatically
• Use vi.spyOn(object, 'method') to observe calls without replacing implementation
• Use test.describe() to group related scenarios; test() for individual cases
• Use test.beforeEach for common setup (navigation, auth state)
• Prefer accessible locators in this order: page.getByRole() > page.getByText() > page.getByLabel() > page.getByTestId()
• Never use CSS/XPath selectors for dynamic content — they break on refactors
• Use extends for shared configs; overrides for file-specific rules
• Never disable a rule without a justifying comment: // eslint-disable-next-line rule-name -- reason
• Prefer configuring rules in the config file over scattering inline disables
• Use error for rules that indicate bugs; warn for stylistic issues being adopted incrementally
• Prettier handles all code formatting — do not manually format or argue about style
• Use eslint-config-prettier to disable ESLint rules that conflict with Prettier
• Never use eslint-plugin-prettier (runs Prettier as an ESLint rule) — it's slow; run them separately
• Use vercel.json for redirects, rewrites, headers, and function configuration
• Set environment variables in the Vercel dashboard (Settings > Environment Variables) — never hardcode secrets
• Use different env var values per environment: Production, Preview, and Development
• Use Edge Runtime (export const runtime = 'edge') for latency-sensitive API routes and middleware