Stack Development Rules

General Rules

• DO NOT TEACH ME HOW TO SET UP THE PROJECT. Assume it's already bootstrapped and ready.
• Start with code. Focus on components, logic, and implementation details.

---

Build & Development Commands

• pnpm dev — Start the Next.js development server.
• pnpm build — Generate production build.
• Database (Drizzle) Commands:
  • pnpm db:generate — Generate SQL migrations from schema.
  • pnpm db:migrate — Apply migrations to the database.
  • pnpm db:push — Push schema changes (rarely used).
  • pnpm db:studio — Launch Drizzle Studio.

---

Testing Guidelines

Unit Testing

• Use Vitest.
  • Test files should use the .test.ts(x) suffix.
  • Colocate tests next to source files.
  • Run tests with pnpm test or pnpm vitest.

End-to-End Testing

• Use Playwright.
  • Store tests in the e2e/ directory.
  • Run with pnpm playwright test.
  • Use pnpm playwright codegen <url> to scaffold flows.
  • Ensure server is running before testing or use start-server-and-test.

---

Code Style & Guidelines

Formatting & Linting

• Use the following scripts for code quality:
  • pnpm format:check — Run Prettier in check mode (ts, tsx, js, jsx, mdx).
  • pnpm format:write — Automatically format files using Prettier.
  • pnpm lint — Run ESLint via next lint.
  • pnpm lint:fix — Fix ESLint issues automatically.
• Do not override Prettier or ESLint config locally — project-level settings must be respected.
• Run both lint and format:check before creating PRs.

TypeScript

• The project uses strict TypeScript mode.
• Avoid any at all costs. If absolutely necessary, use // FIXME: any with an explanation.
• Prefer explicit types in complex logic.
• Use utility types like ReturnType, Pick, and Partial to avoid duplication.
• Align validation and types with Zod schemas wherever possible.

Framework & Logic

• Use Next.js App Router (app/ directory).
  • Prefer server components when applicable.
  • Use layout.tsx, page.tsx, loading.tsx, etc. correctly.
• Use tRPC for typed client-server communication.
• Use Zod for all validation.
• Use Clerk for authentication.
• Use Zustand for state management.
• Use t3-env for safe and validated environment variables.

Styling

• Use Tailwind CSS, with custom variable tokens configured in global styles.
• Use Class Variance Authority (cva) for components with many variants.
• Prefer utility-first styling unless abstraction is justified.

UI Components

• Use Shadcn UI components when available.
• Use Aceternity UI for landing/marketing page components.
• For unavailable components, prefer headless UI libraries and build with the composition pattern.
• Store all custom icons in the icons/ folder and import them — avoid inline SVGs unless necessary.

Modules & Imports

• Use named exports for all components, utils, stores, and libraries.
• Use type modifier for type-only imports:

  import type { User } from "@/types";
  

• Organize imports as:
  1. External libraries
  2. Internal modules (components, utils, hooks, etc.)
  3. Styles
• Prefer absolute imports using @/ instead of long relative paths.
• React component files must use kebab-case:
  • user-card.tsx is RIGHT.
  • UserCard.tsx, userCard.tsx is WRONG.

---

Documentation Guidelines

• Use inline comments and JSDoc for complex business logic and reusable functions.
• For each tRPC router, document:
  • Purpose
  • Input shape
  • Output shape
  • Keep README.md updated for major changes in setup or architecture.