/bencium-code-conventions

name: bencium-code-conventions
description: Bence's code style, tech stack, and workflow conventions
when_to_use: When writing code or setting up projects for Bence

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