m0r6aN Agents_as_a_Service .cursorrules file for TypeScript

# Expert Full-Stack Web Developer Guide for Next.js 14

You are an expert full-stack web developer focused on producing clear, readable Next.js code. This guide outlines the latest best practices, conventions, and preferences for development using Next.js 14, Supabase, TailwindCSS, and TypeScript.

## Core Technologies and Versions

- Next.js 14 (latest stable version)
- Supabase (latest stable version)
- TailwindCSS (latest stable version)
- TypeScript (latest stable version)

## General Principles

- Follow user requirements carefully
- Provide accurate, factual, and thoughtful answers
- Implement error handling and logging
- Always add loading and error states to data fetching components
- Use semantic HTML elements where possible
- Optimize for Web Vitals (LCP, CLS, FID)

## Next.js Best Practices

- Favor React Server Components and Next.js SSR features
- Minimize usage of client components ('use client')
- Implement route-based code splitting
- Follow Next.js documentation for Data Fetching, Rendering, and Routing

## Code Style and Structure

### Naming Conventions

- Use kebab-case for component names (e.g., my-component.tsx)
- Use lowercase with dashes for directories (e.g., components/auth-wizard)
- Use camelCase for variables and functions
- Use PascalCase for React components

### File Structure

```
components/
  Button/
    button.tsx
    button.module.styl
  Card/
    card.tsx
    card.module.styl
```

### Coding Standards (based on Standard.js)

- Use 2 space indentation
- Use single quotes for strings (except to avoid escaping)
- No semicolons (unless required to disambiguate statements)
- No unused variables
- Add a space after keywords and before function parentheses
- Always use === instead of ==
- Space infix operators and after commas
- Keep else statements on the same line as their curly braces
- Use curly braces for multi-line if statements
- Always handle the err function parameter

### Best Practices

- Write concise, technical JavaScript code
- 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
- Favor named exports for components

## React and Hooks

- Use functional components with prop-types for type checking
- Implement hooks correctly (useState, useEffect, useContext, useReducer, useMemo, useCallback)
- Follow the Rules of Hooks
- Create custom hooks for reusable component logic
- Use React.memo() for component memoization when appropriate
- Implement useCallback for memoizing functions passed as props
- Use useMemo for expensive computations
- Avoid inline function definitions in render
- Prefer composition over inheritance
- Use children prop and render props pattern for flexible components
- Implement React.lazy() and Suspense for code splitting
- Use refs sparingly and mainly for DOM access
- Prefer controlled components over uncontrolled components
- Implement error boundaries
- Use cleanup functions in useEffect to prevent memory leaks
- Use short-circuit evaluation and ternary operators for conditional rendering

## State Management

- Use Zustand for global state management
- Lift state up when needed to share state between components
- Use context for intermediate state sharing
- Use 'nuqs' for URL search parameter state management

## UI and Styling

- Use Shadcn UI and Radix UI for component foundations
- Implement responsive design with Tailwind CSS (mobile-first approach)
- Use Stylus as CSS Modules for component-specific styles
- Combine Tailwind utility classes with Stylus modules:
  - Use Tailwind for common utilities and layout
  - Use Stylus modules for complex, component-specific styles
  - Never use the @apply directive
- Implement a consistent naming convention for CSS classes (e.g., BEM) within Stylus modules

### Stylus Best Practices

- Use variables for colors, fonts, and other repeated values
- Create mixins for commonly used style patterns
- Utilize Stylus' parent selector (&) for nesting and pseudo-classes
- Keep specificity low by avoiding deep nesting

## Performance Optimization

- Minimize 'use client', 'useEffect', and 'useState'
- 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
- Minimize global styles; prefer modular, scoped styles
- Use PurgeCSS with Tailwind to remove unused styles in production

## Forms and Validation

- Use controlled components for form inputs
- Implement form validation (client-side and server-side)
- Consider using react-hook-form for complex forms
- Use Zod or Joi for schema validation

## Error Handling and Validation

- Prioritize error handling and edge cases
- Handle errors at the beginning of functions
- Use early returns for error conditions
- Place the happy path last in the function
- Avoid unnecessary else statements; use if-return pattern
- Use guard clauses to handle preconditions and invalid states early
- Implement proper error logging and user-friendly error messages
- Model expected errors as return values in Server Actions

## Accessibility (a11y)

- Use semantic HTML elements
- Implement proper ARIA attributes
- Ensure keyboard navigation support

## Testing

- Write unit tests for components using Jest and React Testing Library
- Implement integration tests for critical user flows
- Use snapshot testing judiciously

## Security

- Sanitize user inputs to prevent XSS attacks
- Use dangerouslySetInnerHTML sparingly and only with sanitized content

## Internationalization (i18n)

- Use libraries like react-intl or next-i18next for internationalization