Code Conventions

Core Technologies

• Frontend: ReactJS, Next.js (App Router structure), TypeScript
• Styling: TailwindCSS v3.x (never v4), Shadcn UI
• Build Tools: Vite (when applicable)
• Backend: Postgres compatible convex.dev or Supabase (always ask, never local postgres)
• Deployment: Netlify or Vercel or Fly - suggest
• Environment: Mac M2, Python3 with virtual environments, no CUDA, no Docker
• Alternative Languages: Avoid python if you can, try using RUST

Code Style & Structure

• Use ES modules (import/export) syntax
• Destructure imports when possible
• Use TypeScript for all new code
• Use async/await instead of Promise chains
• Prefer const/let over var; use early returns
• Use consts instead of functions:

  const toggle = () =>

  . Define types.
• Use descriptive variable names with auxiliary verbs (e.g.,

  isLoading

  ,

  hasError

  )
• Use lowercase with dashes for directory names (e.g.,

  components/auth-wizard

  )

Framework Conventions

• Next.js: Use App Router (app directory) structure and page.tsx files
• React: Functional and declarative patterns; avoid classes
• State Management: Zustand, TanStack React Query
• Validation: Zod for schema validation

Component Library & Styling

• Component Library: Prefer shadcn components from

  @/components/ui

• Styling: Tailwind utility classes
• Layout: Grid/flex wrappers with

  gap

  for spacing
• Icons:

  @phosphor-icons/react

• Toasts:

  sonner

  for notifications
• Always add loading states, spinners, placeholder animations

Quality Assurance & Testing

• TDD: Write failing tests first, commit them, then iterate until suite passes
• Never mock tests - if there's a test script, execute all until done
• Always write SQL in chunks with test steps after each chunk
• Typecheck after making code changes
• Run tests before committing
• Prefer running single tests for performance, not whole suite

Error Handling

• Implement proper error handling and user input validation
• Error messages should be understood by non-technical people
• Use early returns for error conditions
• Test APIs via curl commands first, then implement in code

Performance & Architecture

• Minimize

  'use client'

  ,

  useEffect

  ,

  setState

  ; favor RSC and Next.js SSR
• Implement dynamic imports for code splitting
• Optimize images: WebP format, size data, lazy loading
• Favor small, simple, well-named modules

Development Workflow

• Read relevant files
• Think through a plan
• Implement
• Then commit
• Never local backend, always ask (usually Supabase, Neon)
• Minimal dependency, no docker

Environment & Deployment

• Add .env files for API keys; warn me to save keys in Vercel/Netlify env variables
• Write code deployable to Netlify or Vercel; prepare to build locally first
• Document progress in progress.md; ask for implementation plan