loki/.cursor/rules/frontend.mdc

---
description: building frontend code in react and typescript
globs: *.tsx,*.ts,*.css
---
You are an expert in TypeScript, Node.js, react-dom router, React, Shadcn UI, Radix UI and Tailwind.

# Key Principles

- Write concise, technical TypeScript code with accurate examples.
- Use functional and declarative programming patterns; avoid classes.
- Prefer iteration and modularization over code duplication.
- Use descriptive variable names with auxiliary verbs (e.g., isLoading, hasError).
- Structure files: exported component, subcomponents, helpers, static content, types.

# Component Composition

Break down complex UIs into smaller, more manageable parts, which can be easily reused across different parts of the application.

- Reusability: Components can be easily reused across different parts of the application, making it easier to maintain and update the UI.
- Modularity: Breaking the UI down into smaller, more manageable components makes it easier to understand and work with, particularly for larger and more complex applications.
- Separation of Concerns: By separating the UI into smaller components, each component can focus on its own specific functionality, making it easier to test and debug.
- Code Maintainability: Using smaller components that are easy to understand and maintain makes it easier to make changes and update the application over time.

Avoid large components with nested rendering functions


# State

- useState - for simpler states that are independent
- useReducer - for more complex states where on a single action you want to update several pieces of state
- context + hooks = good state management don't use other library
- prefix -context and -provider for context and respective provider.

# Naming Conventions

- Use lowercase with dashes for directories (e.g., components/auth-wizard).
- Favor named exports for components.

# TypeScript Usage

- Use TypeScript for all code; prefer interfaces over types.
- Avoid enums; use maps instead.
- Use functional components with TypeScript interfaces.

# Syntax and Formatting

- Use the "function" keyword for pure functions.
- Avoid unnecessary curly braces in conditionals; use concise syntax for simple statements.
- Use declarative JSX.
- Use arrow functions for improving code readability and reducing verbosity, especially for smaller functions like event handlers or callback functions.
- Avoid using inline styles

## Project Structure

Colocate things as close as possible to where it's being used

```
src/
├── components/           # React components
│   ├── ui/              # Shadcn UI components
│   │   ├── errors/      # Error handling components
│   │   └── breadcrumbs/ # Navigation breadcrumbs
│   ├── shared/          # Shared components used across pages
│   │   └── {pagename}/  # Page-specific components
│   ├── common/          # Truly reusable components
│   └── features/        # Complex feature modules
│       └── theme/       # Theme-related components and logic
├── pages/               # Page components and routes
├── layout/              # Layout components
├── hooks/               # Custom React hooks
├── contexts/            # React context providers
├── lib/                # Utility functions and constants
└── types/              # TypeScript type definitions
```

DON'T modify shadcn component directly they are stored in  src/components/ui/*


# UI and Styling

- Use Shadcn UI, Radix, and Tailwind for components and styling.
- Implement responsive design with Tailwind CSS.

# Performance Optimization

- Minimize 'use client', 'useEffect', and 'setState'; favor React Server Components (RSC).
- Wrap client components in Suspense with fallback.
- Use dynamic loading for non-critical components.
- Optimize images: use WebP format, include size data, implement lazy loading.

# Key Conventions

- Use 'nuqs' for URL search parameter state management.
- Optimize Web Vitals (LCP, CLS, FID).
- Limit 'use client':

# Unit Tests

Unit testing is done to test individual components of the React application involving testing the functionality of each component in isolation to ensure that it works as intended.

- Use Jest for unit testing.
- Write unit tests for each component.
- Use React Testing Library for testing components.
- Use React Testing Library for testing components.