# Rules for MERN Stack and Vite Applications
mern_stack_rules:
  # Architecture & Project Structure
  - Enforce a clear folder structure: `src/models`, `src/controllers`, `src/routes`, `src/middleware`, `src/utils`.
  - Use environment variables via `dotenv` and validate with `joi` or `zod` at startup.
  - Define Express app in `app.js`, separate server startup in `server.js`.
  - Centralize configuration in a `config/` module (database, cache, third-party keys).

  # API & Routing
  - Follow RESTful conventions: map CRUD operations to HTTP verbs.
  - Use Express Router for modular route definitions; group by resource.
  - Implement input validation with `joi` or `zod` in middleware.
  - Standardize responses: `{ success: boolean, data: any, error?: string }`.

  # Authentication & Security
  - Use JWT for auth; store secrets securely via environment variables.
  - Protect routes with auth middleware; allow role-based access controls.
  - Sanitize user input to prevent injection attacks (e.g., `express-validator`).
  - Apply security headers via `helmet`, enable CORS via `cors`.

  # Database Layer
  - Use Mongoose for MongoDB interactions; define strict schemas with TypeScript or JSDoc.
  - Maintain a single connection instance; handle disconnects on errors gracefully.
  - Implement soft deletes with a `deletedAt` timestamp field pattern.
  - Encapsulate database calls in service modules for testability.

  # Error Handling & Logging
  - Create a global error handler middleware catching sync and async errors.
  - Use custom Error classes (e.g., `ValidationError`, `AuthError`).
  - Log errors and requests with `winston` or `pino`; store logs centrally in JSON format.

  # Testing
  - Write unit tests for controllers/services using Jest and Supertest.
  - Mock external dependencies (DB, email) for isolated tests.
  - Enforce 80% coverage; run tests in CI pipelines.

  # General JavaScript Standards
  - Adhere to the Airbnb style guide; lint with ESLint and Prettier on save.
  - Use ES6+ features: `async/await`, destructuring, modules.
  - Avoid `any` in TypeScript; prefer strict typing and interfaces.

vite_app_rules:
  # Vite Configuration
  - Define aliases in `vite.config.js` under `resolve.alias` for `@/components`, `@/utils`.
  - Use `dotenv` and `vite-plugin-env-compatible` to load and validate env variables.
  - Optimize dependencies with `optimizeDeps.include` and `exclude` as needed.

  # React & Component Patterns
  - Use PascalCase for component filenames; index exports for simplicity.
  - Separate presentational and container components; follow `FeatureView/FeatureContainer` pattern.
  - Mark client-only modules in SSR setups explicitly; avoid server bundling of browser-only APIs.

  # Styling & CSS
  - Integrate Tailwind CSS via `tailwind.config.cjs`; use `@apply` sparingly in CSS modules.
  - Centralize design tokens (colors, spacing) in Tailwind theme; follow mobile-first breakpoints.
  - Use `clsx` for conditional classNames; avoid inline style objects.

  # State Management & Data Fetching
  - Use React Context for UI state (theme, modals); use Zustand or Redux Toolkit for complex stores.
  - Integrate TanStack Query (React Query) for server data; configure a global `QueryClient`.
  - Standardize query keys; handle staleTime and retry strategies.

  # Form Handling
  - Use React Hook Form with Zod for validation; integrate with UI library form components.
  - Show loading and error states using `formState` hooks.

  # UI Libraries & Plugins
  - Install UI components via `npx shadcn-ui add [component]`; override styles via `className`, not core files.
  - Implement dark mode toggles with `next-themes` or `useTheme` hooks.

  # Performance & Build Optimization
  - Enable code splitting via dynamic imports and React.lazy.
  - Use `@vitejs/plugin-react-swc` or similar for faster builds.
  - Generate source maps only in development; minify code in production builds.

  # Testing & Linting
  - Use Vitest for unit tests; mock modules with `vi.mock`.
  - Lint with ESLint configured for React and TypeScript; run in pre-commit hooks via Husky.
```