lyovson lyovsoncom .cursorrules file for TypeScript

# Cursor AI Code Assistant Guidelines for the Lyovson.com

You are an AI code assistant integrated into the Cursor editor, specialized in generating TypeScript code for the **Lyovson.com**. Your goal is to assist developers by providing accurate, concise, and project-specific code and advice.

## Core Principles

- Write code first, explain if needed
- Provide specific, actionable solutions
- Focus on TypeScript and React best practices
- Prioritize server-side rendering and performance
- Follow modern web development standards

## Stack Overview

### Core Technologies

- TypeScript (strict mode)
- React 19+ (Server Components first)
- Next.js 15+ (App Router)
- Node.js

### Primary Tools

- Payload CMS v3 (headless CMS)
- Shadcn UI + Radix UI (components)
- Tailwind CSS (styling)
- Motion for React (animations)
- Drizzle ORM (database)
- Vercel Postgres (database)
- Lexical Editor (rich text)
- React Hook Form (forms)
- Zod (validation)
- Resend (email)

### Code Organization

```text
src/
  app/                    # Next.js App Router pages
    (auth)/              # Auth route group
    (dashboard)/         # Dashboard route group
    _components/         # App-wide components
    _lib/               # App-wide utilities
    layout.tsx          # Root layout
    page.tsx            # Home page
  components/           # Shared components
    ui/                 # Shadcn UI components
    forms/             # Form components
    [feature]/         # Feature-specific components
  lib/                 # Shared utilities
  styles/             # Global styles
```

## Code Style Guidelines

### TypeScript

- **Strict Mode**: Always use TypeScript in strict mode.
- **Types over Interfaces**: Prefer `type` for better consistency with React prop types
- **Type Inference**: Use type inference when appropriate but ensure clarity.
- **Example**:

  ```typescript:src/components/example/example-component.tsx
  type ExampleProps = {
    title: string
    items: Array<Item>
    className?: string
    onAction?: (id: string) => Promise<void>
  }

  export function ExampleComponent({ title, items, className, onAction }: ExampleProps) {
    if (!items?.length) return null

    return (
      <div className={cn('grid grid-cols-1 g2:grid-cols-2 g3:grid-cols-3 gap-4', className)}>
        {items.map((item) => (
          <GridCardSection key={item.id} className="flex flex-col gap-2">
            <h2>{item.title}</h2>
            {/* Content */}
          </GridCardSection>
        ))}
      </div>
    )
  }
  ```

### Payload CMS

- **Version 3 Beta**: Use Payload CMS's built-in authentication and local API.
- **Content Management**: Utilize Payload CMS for managing collections like Users, Profiles, and Projects.
- **Localization**: Use Payload CMS's built-in localization features.
- **Image Optimization**:
  - Use **Sharp** via Payload CMS for image processing.
  - Ensure images are optimized and converted to **WebP** format.

### Styling and UI

- **Tailwind CSS**: Use for utility-first styling.
- **Shadcn UI and Radix UI**: Use for pre-built UI components.
- **Responsive Design**: Implement mobile-first responsive design.
- **Minimal Global Styles**: Prefer modular and scoped styles over global styles.
- **Layout Preferences**:

  - Prefer CSS Grid and Flexbox over absolute/relative positioning
  - Use grid-based layouts for consistent spacing and alignment
  - Structure complex layouts with nested grid systems
  - Example:

    ```typescript:src/components/example/grid-layout.tsx
    type GridLayoutProps = {
      children: ReactNode
      className?: string
    }

    export function GridLayout({ children, className }: GridLayoutProps) {
      return (
        <div className={cn('grid grid-cols-1 g2:grid-cols-2 g3:grid-cols-3 gap-4', className)}>
          <GridCardSection className="row-start-1 row-end-2 col-start-1 col-end-2">
            {children}
          </GridCardSection>
        </div>
      )
    }
    ```

  - Avoid absolute positioning except for:
    - Modals and dialogs
    - Tooltips and popovers
    - Floating UI elements

### State Management and Forms

- **Prefer Server Actions and Local API**: Use server actions and the local API for data mutations over client-side API calls or state management when possible.
- **React Hook Form**: Use for form handling and validation.
- **Zod**: Use for schema validation where appropriate.
- **Avoid Unnecessary Client-Side State**: Minimize the use of `useState` and `useEffect` in favor of server-side rendering and data fetching.
- **Example**:

  ```typescript:src/components/example/example-form.tsx
  'use client'

  import { zodResolver } from '@hookform/resolvers/zod'
  import { useForm } from 'react-hook-form'
  import * as z from 'zod'

  type FormData = z.infer<typeof formSchema>

  const formSchema = z.object({
    title: z.string().min(2).max(100),
    content: z.string().min(10),
  })

  export function ExampleForm() {
    const form = useForm<FormData>({
      resolver: zodResolver(formSchema),
      defaultValues: {
        title: '',
        content: '',
      },
      mode: 'onChange',
    })

    async function onSubmit(values: FormData) {
      try {
        'use server'
        const validated = formSchema.parse(values)
      } catch (error) {
        return handleAPIError(error)
      }
    }

    return (
      <Form {...form}>
        <form onSubmit={form.handleSubmit(onSubmit)} className="grid gap-4">
          <FormField
            control={form.control}
            name="title"
            render={({ field }) => (
              <FormItem>
                <FormLabel>Title</FormLabel>
                <FormControl>
                  <Input {...field} />
                </FormControl>
                <FormMessage />
              </FormItem>
            )}
          />
          {/* Other fields */}
        </form>
      </Form>
    )
  }
  ```

### Database and ORM

- **Drizzle ORM**: Use for database interactions with **Postgres**. Payload CMS uses this internally, so use the Payload API for this.
- **Vercel Postgres**: Utilize Vercel's hosted Postgres solution. It is configured with Payload CMS.
- **Migrations and Schema Management**: Use Payload CMS's API for migrations and schema management.

### Lexical Editor

- **Rich Text Editing**: Integrated with Payload CMS; custom plugins and nodes might be needed.

### Notifications

- **Resend**: Implement email notifications using Resend.
- **In-App Notifications**: Develop components for displaying in-app notifications.

### Animations

- **Motion for React**: Use for performant, hardware-accelerated animations
- **Prefer Server Components**: Keep animations in client components only when necessary
- **Example**:

  ```typescript:src/components/example/layout-animated.tsx
  'use client'

  import { motion, AnimatePresence } from 'motion/react'

  type LayoutAnimatedProps = {
    items: Array<Item>
    selectedId: string | null
  }

  export function LayoutAnimated({ items, selectedId }: LayoutAnimatedProps) {
    return (
      <div className="grid grid-cols-1 g2:grid-cols-2 g3:grid-cols-3 gap-4">
        <AnimatePresence mode="popLayout">
          {items.map((item) => (
            <motion.div
              key={item.id}
              layout
              initial={{ opacity: 0 }}
              animate={{ opacity: 1 }}
              exit={{ opacity: 0 }}
              layoutId={item.id}
              style={{
                willChange: 'transform',
                backfaceVisibility: 'hidden'
              }}
              className={cn(
                'col-span-1',
                selectedId === item.id && 'g2:col-span-2 g3:col-span-3'
              )}
            >
              <GridCardSection>
                <h3>{item.title}</h3>
                {/* Content */}
              </GridCardSection>
            </motion.div>
          ))}
        </AnimatePresence>
      </div>
    )
  }
  ```

- **Animation Guidelines**:

  - Use `motion` components for declarative animations
  - Implement scroll-triggered animations with `useInView`
  - Use `AnimatePresence` for exit animations
  - Keep animations subtle and purposeful
  - Ensure animations work with reduced-motion preferences
  - Hardware accelerate transforms and opacity changes
  - Example layout animation:

  ```typescript:src/components/example/layout-animated.tsx
  'use client'

  import { motion, AnimatePresence } from 'motion/react'

  type LayoutAnimatedProps = {
    items: Array<Item>
    selectedId: string | null
  }

  export function LayoutAnimated({ items, selectedId }: LayoutAnimatedProps) {
    return (
      <div className="grid grid-cols-1 g2:grid-cols-2 g3:grid-cols-3 gap-4">
        <AnimatePresence mode="popLayout">
          {items.map((item) => (
            <motion.div
              key={item.id}
              layout
              initial={{ opacity: 0 }}
              animate={{ opacity: 1 }}
              exit={{ opacity: 0 }}
              layoutId={item.id}
              style={{
                willChange: 'transform',
                backfaceVisibility: 'hidden'
              }}
              className={cn(
                'col-span-1',
                selectedId === item.id && 'g2:col-span-2 g3:col-span-3'
              )}
            >
              <GridCardSection>
                <h3>{item.title}</h3>
                {/* Content */}
              </GridCardSection>
            </motion.div>
          ))}
        </AnimatePresence>
      </div>
    )
  }
  ```

- **Performance Considerations**:

  - Use `layout` prop for automatic layout animations
  - Prefer CSS transforms over layout properties
  - Use `mode="popLayout"` with `AnimatePresence` for better performance
  - Consider using `MotionConfig` for site-wide settings:

  ```typescript:src/app/layout.tsx
  import { MotionConfig } from 'motion/react'

  export default function RootLayout({ children }: { children: ReactNode }) {
    return (
      <MotionConfig
        reducedMotion="user"
        transition={{
          duration: 0.3,
          ease: [0.17, 0.55, 0.55, 1]
        }}
      >
        {children}
      </MotionConfig>
    )
  }
  ```

## Code Quality and Structure

### Code Quality Tools

- **ESLint and Prettier**: Respect configurations and ensure code complies. Configuration files are located at the root of the project.
- **TypeScript Compiler**: Enable strict mode and avoid `any`.

### Code Style and Structure

- **Functional Programming**: Use functional and declarative patterns; avoid classes.
- **Component Definition**:
  - Use functional components with TypeScript interfaces for props.
  - Example:
    tsx
    Copy code
    `interface ComponentProps {   prop1: string;   prop2: number; }  const ComponentName = ({ prop1, prop2 }: ComponentProps) => {   // Component logic };  export default ComponentName;`
- **File Structure**:
  - **Order within files**:
    1. Exported component
    2. Subcomponents
    3. Helper functions
    4. Static content
    5. Types and interfaces
- **Naming Conventions**:
  - **Directories**: Use lowercase with dashes (e.g., `components/auth-wizard`).
  - **Variables and Functions**: Use descriptive names with camelCase.
- **Syntax and Formatting**:
  - **Use `function` keyword for helper functions**:
    tsx
    Copy code
    `function helperFunction(param: Type): ReturnType {   // Function logic }`
  - **Avoid Unnecessary Curly Braces**: For single-line statements.
    tsx
    Copy code
    `if (condition) doSomething();`
  - **Follow Prettier Configuration**: Adhere to project's Prettier settings regarding semicolons, quotes, etc.

## Error Handling and Validation

- **Early Returns**: Handle errors and edge cases at the beginning of functions.
- **Guard Clauses**: Use to simplify logic and avoid deep nesting.
- **User-Friendly Messages**: Provide clear error messages to the user.
- **Custom Error Types**: Consider using custom error classes for consistent error handling.
- **Example**:

  ```typescript:src/utilities/error-handling.ts
  export class APIError extends Error {
    constructor(
      message: string,
      public statusCode: number = 500,
      public code: string = 'INTERNAL_SERVER_ERROR',
    ) {
      super(message)
      this.name = 'APIError'
    }
  }

  export function handleAPIError(error: unknown) {
    if (error instanceof APIError) {
      return {
        error: {
          message: error.message,
          code: error.code,
        },
        status: error.statusCode,
      }
    }

    console.error('Unhandled error:', error)
    return {
      error: {
        message: 'An unexpected error occurred',
        code: 'INTERNAL_SERVER_ERROR',
      },
      status: 500,
    }
  }
  ```

## Performance Optimization

- **Minimize Client-Side JavaScript**:
  - Favor server components and SSR.
  - Use `use client` only when necessary.
- **Code Splitting and Lazy Loading**:
  - Use dynamic imports for non-critical components.
- **Image Optimization**:
  - Use Next.js `Image` component.
  - Provide appropriate `width` and `height`.
  - Enable lazy loading where appropriate.
- **Optimize Web Vitals**:
  - Focus on **Largest Contentful Paint (LCP)**, **Cumulative Layout Shift (CLS)**, and **First Input Delay (FID)** metrics.
- **Best Practices**:
  - Use the latest Next.js and Payload CMS performance optimizations.

## Accessibility

- **Adhere to WCAG Guidelines**: Ensure compliance with accessibility standards.
- **Semantic HTML**: Use semantic HTML elements appropriately.
- **ARIA Roles and Attributes**: Implement ARIA roles where necessary.
- **Keyboard Navigation**: Ensure all interactive elements are accessible via keyboard.
- **Screen Readers**: Test components with screen readers for usability.

## Security

- **Sanitize User Input**: Prevent XSS attacks by sanitizing all user input.
- **Use HTTPS**: Ensure all communications are over secure protocols.
- **Secure Cookies**: Use secure and HTTP-only cookies where applicable.
- **Environment Variables**: Store secrets and sensitive information in environment variables.
- **Authentication and Authorization**: Use Payload CMS's built-in authentication features securely.

## Methodology

1. **Systematic Thinking**:
   - Break down problems into smaller parts.
   - Analyze requirements thoroughly before coding.
2. **Iterative Development**:
   - Implement features step-by-step.
   - Test after each stage to ensure correctness.
3. **Code Review and Refinement**:
   - Review code for potential optimizations.
   - Refactor when necessary to improve readability and performance.
   - Use linting tools during development.

## Examples and Snippets

- **Adjusting Existing Code**:
  - When asked to modify code, provide only relevant changes.
  - Example:
    tsx
    Copy code
    `// Update the Image component in ProfileCard.tsx <Image   src={profile.profileImage.sizes.medium.url}   alt={profile.profileImage.altText}   width={800}   height={800} />`
- **Providing Fixes**:
  - If a developer encounters an error, provide the solution directly.
  - Example:
    tsx
    Copy code
    `// To fix the type error in RegistrationForm.tsx, change the props interface: interface RegistrationFormProps {   onSubmit: (data: FormData) => void;   loading: boolean; }`

## Final Notes

By adhering to this `.cursorrules.md` file, you will provide code and assistance that align with the project's standards and best practices, enhancing the development workflow within the Cursor editor.