dafthunk / rules

---
description: Coding standards, naming, testing & style rules
globs: 
alwaysApply: true
---
# Development Guidelines

## General
- Write **correct, DRY, bug-free** code — leave **no TODOs**.
- Prefer **functional components** and **hooks**; use **TypeScript** types/interfaces consistently.
- Use **early returns** to reduce nesting.
- Choose **descriptive names** for variables, functions, and components.

## Typing
- Use **strict TypeScript**: avoid `any`, `unknown`, and implicit `any`.
- Prefer `interface` over `type` aliases, unless a type cannot be expressed with an interface.
- Always type:
  - Props
  - State
  - Event handlers
  - Returned values
- Favor **`readonly`** and **`as const`** assertions for immutability and safety.
- Narrow types when possible (e.g., `'small' | 'medium' | 'large'` instead of `string`).
- Use utility types like `Partial`, `Pick`, `Omit` thoughtfully to improve clarity and type safety.

## Styling
- Use **Tailwind CSS** exclusively — do not use external CSS or styled-components.
- Use the `cn` utility from `@/utils/utils` for conditional class names.
  - Avoid ternaries in className strings.

## Naming Conventions
- **kebab-case** for file names (e.g., `my-component.tsx`).
- **camelCase** for hooks and utility functions (e.g., `useMyHook`, `formatDate`).
- Prefix event handlers with `handle` (e.g., `handleSubmit`, `handleClick`).

## Testing & QA
- Write tests using **Vitest**.
- Cover critical paths, edge cases, and user-facing logic.
- Provide fallback UI and error boundaries where appropriate.

## REST API Best Practices

### Shared Types
- Define shared types in: `packages/types/src/index.ts`
- Use them:
  - To serialize data in API routes (backend).
  - To deserialize and validate data on the frontend.
- This ensures **type safety and consistency** across backend and frontend.

### Statelessness
- REST APIs must be **stateless**:
  - Each request must be self-contained.
  - The server must not depend on in-memory or session state.
- Clients manage session (e.g., cookies, auth headers, tokens).
- Use headers or tokens to communicate user context, not prior API calls.

#### Benefits
- Enables better scalability and server independence.
- Reduces bugs and improves debuggability by avoiding implicit state.