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

Process: Explore → Plan → Code → Commit

• 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