Awesome Cursor Rules Collection

You are an expert in React, Vite, Tailwind CSS, three.js, GASP, Next UI and React three fiber.
  
Key Principles
  - Write concise, technical responses with accurate React examples.
  - Use functional, declarative programming. Avoid classes.
  - Prefer iteration and modularization over duplication.
  - Use descriptive variable names with auxiliary verbs (e.g., isLoading).
  - Use lowercase with dashes for directories (e.g., components/auth-wizard).
  - Favor named exports for components.
  - Use the Receive an Object, Return an Object (RORO) pattern.
  
JavaScript
  - Use "function" keyword for pure functions. Omit semicolons.
  - Use TypeScript for all code. Prefer interfaces over types. Avoid enums, use maps.
  - File structure: Exported component, subcomponents, helpers, static content, types.
  - Avoid unnecessary curly braces in conditional statements.
  - For single-line statements in conditionals, omit curly braces.
  - Use concise, one-line syntax for simple conditional statements (e.g., if (condition) doSomething()).
  
Error Handling and Validation
    - Prioritize error handling and edge cases:
    - Handle errors and edge cases at the beginning of functions.
    - Use early returns for error conditions to avoid deeply nested if statements.
    - Place the happy path last in the function for improved readability.
    - Avoid unnecessary else statements; use if-return pattern instead.
    - Use guard clauses to handle preconditions and invalid states early.
    - Implement proper error logging and user-friendly error messages.
    - Consider using custom error types or error factories for consistent error handling.
  
React
  - Use functional components and interfaces.
  - Use declarative JSX.
  - Use function, not const, for components.
  - Use Next UI, and Tailwind CSS for components and styling.
  - Implement responsive design with Tailwind CSS.
  - Implement responsive design.
  - Place static content and interfaces at file end.
  - Use content variables for static content outside render functions.
  - Wrap client components in Suspense with fallback.
  - Use dynamic loading for non-critical components.
  - Optimize images: WebP format, size data, lazy loading.
  - Model expected errors as return values: Avoid using try/catch for expected errors in Server Actions. Use useActionState to manage these errors and return them to the client.
  - Use error boundaries for unexpected errors: Implement error boundaries using error.tsx and global-error.tsx files to handle unexpected errors and provide a fallback UI.
  - Use useActionState with react-hook-form for form validation.
  - Always throw user-friendly errors that tanStackQuery can catch and show to the user.


In the provided 3JS scene, we can observe a 3D grid of boxes, each of which appears to animate and morph based on the progress parameter, as follows:

    - Initial Scene (Progress = 0):
        - At the start, the scene consists of a grid of blue, block-like cubes arranged neatly in rows.
        - The color of the boxes shifts subtly from dark blue to lighter blue, suggesting a gradient or lighting effect applied across the grid.
        - The center of the grid features a single, different element: a black rectangle with a green square in its middle. This may be part of an object or entity being animated.
        - Lighting seems basic, likely ambient and possibly directional, with light sources emphasizing the color variations on the cubes.
    
    - Mid-Point (Progress = 0.5):
        - As the progress value increases to 0.5, the scene shows significant changes.
        - The boxes have begun to morph. Some have disappeared or appear sunken into the grid, while others form new shapes.
        - The central black rectangle with the green element is now a green abstract shape, possibly a silhouette or map-like shape. This could signify the morphing or transformation in progress.
        - The lighting continues to emphasize the depth and gradient of the cubes, making them visually stand out more as the scene evolves. A more pronounced shadow effect suggests the light source’s angle has either shifted or been altered during the animation.
    
    - Final Scene (Progress = 1):
        - At this stage, the scene shows a significant transformation. The cubes are more scattered, some having morphed into a larger, irregular shape.
        - The abstract green shape remains central, and the grid itself has dramatically changed, as cubes have repositioned themselves or disappeared altogether.
        - The zoomed-out perspective reveals more of the environment, suggesting the cubes are not constrained to a strict grid anymore.
        - Lighting plays an even more critical role here in illuminating the edges of the cubes and the transformed shapes, giving depth to the newly morphed object. There seems to be a directional light that highlights the boxes’ edges and shadows on the unlit sides.

Key Details for Prompt Engineering:

    - Cubes: Uniform cubes that are animated to morph over time, likely using vertex shaders to alter their position and size, with dynamic control via a progress parameter.
    - Central Object: An abstract green shape that evolves as the progress increases, likely driven by a fragment shader to control its color and opacity.
    - Lighting: There’s directional lighting creating gradients and shadows across the cubes, enhancing the sense of depth. There is likely an ambient light to maintain base visibility across the scene.
    - Shaders: Vertex shaders control the positions and deformation of the cubes, while fragment shaders handle color transitions (blue to light blue) and the material of the objects. The black rectangle with the green element suggests some use of texture or mapping techniques.

# Embedded Finance Components Cursor Rules

## Repository Structure

This is a monorepo containing multiple packages:

```
/
├── app/                    # Showcase web application (not active)
│   ├── client/            # Frontend React application
│   └── server/            # Backend server
├── embedded-components/    # Main UI component library (active)
│   ├── src/               # Source code
│   ├── .storybook/        # Storybook configuration
│   ├── dist/              # Built files (not in repo)
│   └── public/            # Static assets and MSW worker
└── embedded-finance-sdk/   # TypeScript SDK utilities (not active)
```

> **Note**: Currently, active development is focused on the `embedded-components` package. Other packages are planned for future development.

## Active Package: embedded-components

The `embedded-components` package is our primary UI component library for embedded finance solutions.

## Technology Stack Reference

- React 18.x with TypeScript
- Radix UI primitives
- Tailwind CSS
- Vite & TypeScript
- Storybook 8.x
- MSW for API mocking
- Tanstack React Query v5
- Zod validation

## Component Creation Guidelines

### 1. Component Planning Phase

1. Carefully analyze the component's purpose and requirements
2. Review existing components in:
   - `src/core/`
   - `src/components/`
3. Check if similar functionality exists in Radix UI primitives

### 2. Component Structure Requirements

1. Location: Place new components in `src/core/` or appropriate subdirectory
2. File Structure:
   ```
   ComponentName/
   ├── ComponentName.tsx          # Main component
   ├── ComponentName.test.tsx     # Tests
   ├── ComponentName.story.tsx    # Storybook
   ├── ComponentName.schema.ts    # Validation schema (if needed)
   └── index.ts                   # Exports
   ```

### 3. Component Implementation Rules

1. Use TypeScript with strict mode
2. Implement as functional components with hooks
3. Follow React 18 best practices:
   - Use proper error boundaries
   - Implement React Query for data fetching
   - Use Orval generated types and react-query hooks
4. Styling:

   - Use Tailwind CSS for styling
   - Prefix custom Tailwind classes with `eb-` for embedded components
   - Example:

     ```typescript
     // In your component
     <div className="eb-custom-class">

     // In tailwind.config.js
     module.exports = {
       theme: {
         extend: {
           // Custom classes should be prefixed
           '.eb-custom-class': {
             // styles
           }
         }
       }
     }
     ```

   - Follow project color scheme and design tokens
   - Ensure responsive design

5. Props:
   - Define clear prop interfaces
   - Use proper TypeScript types
   - Document all props in JSDoc format

### 4. Testing Requirements

1. **Test Setup and Utilities**:

   ```typescript
   import { render, screen, waitFor } from "@testing-library/react";
   import { userEvent } from "@test-utils";
   import { http, HttpResponse } from "msw";
   import { server } from "@/msw/server";
   import { QueryClient, QueryClientProvider } from "@tanstack/react-query";

   // Setup QueryClient for tests
   const queryClient = new QueryClient();

   // Mock data setup
   const mockData = {
     // Component-specific mock data
   };

   // Mock context if needed
   const mockContext = {
     // Context-specific mock data
   };
   ```

2. **Component Rendering Helper**:

   ```typescript
   const renderComponent = () => {
     // Reset MSW handlers before each render
     server.resetHandlers();

     // Setup explicit API mock handlers
     server.use(
       http.get("/api/endpoint", () => {
         return HttpResponse.json(mockData);
       })
     );

     return render(
       <EBComponentsProvider
         apiBaseUrl="/"
         headers={{}}
         contentTokens={{
           name: "enUS",
         }}
       >
         <QueryClientProvider client={queryClient}>
           <ComponentName />
         </QueryClientProvider>
       </EBComponentsProvider>
     );
   };
   ```

3. **Test Structure**:

   ```typescript
   describe("ComponentName", () => {
     // Mock external dependencies
     vi.mock("@/components/ui/someComponent", () => ({
       useSomeHook: () => ({ someFunction: vi.fn() }),
     }));

     test("renders correctly with initial data", async () => {
       renderComponent();

       // Wait for async operations
       await waitFor(() => {
         expect(screen.getByText(/expected text/i)).toBeInTheDocument();
       });
     });

     test("handles user interactions", async () => {
       renderComponent();

       // Simulate user actions
       await userEvent.click(screen.getByRole("button", { name: /action/i }));

       // Verify state changes
       expect(screen.getByText(/new state/i)).toBeInTheDocument();
     });

     test("handles API interactions", async () => {
       // Setup specific API mock for this test
       server.use(
         http.post("/api/endpoint", () => {
           return HttpResponse.json({ success: true });
         })
       );

       renderComponent();

       // Trigger API call
       await userEvent.click(screen.getByRole("button", { name: /submit/i }));

       // Verify API interaction results
       await waitFor(() => {
         expect(screen.getByText(/success/i)).toBeInTheDocument();
       });
     });
   });
   ```

4. **MSW API Mocking Patterns**:

   ```typescript
   // Setup mock handlers
   server.use(
     // GET requests
     http.get("/api/resource/:id", ({ params }) => {
       return HttpResponse.json(mockData[params.id]);
     }),

     // POST requests with response validation
     http.post("/api/resource", async ({ request }) => {
       const body = await request.json();
       if (!isValidData(body)) {
         return HttpResponse.json({ error: "Invalid data" }, { status: 400 });
       }
       return HttpResponse.json({ success: true });
     }),

     // Error scenarios
     http.get("/api/error-case", () => {
       return HttpResponse.json(
         { error: "Something went wrong" },
         { status: 500 }
       );
     })
   );
   ```

5. **Context and Provider Testing**:

   ```typescript
   // For components using multiple contexts
   const renderWithProviders = (ui: React.ReactElement) => {
     return render(
       <EBComponentsProvider apiBaseUrl="/" headers={{}}>
         <FeatureContextProvider value={mockFeatureContext}>
           <QueryClientProvider client={queryClient}>{ui}</QueryClientProvider>
         </FeatureContextProvider>
       </EBComponentsProvider>
     );
   };

   // Testing context updates
   test("responds to context changes", async () => {
     const { rerender } = renderWithProviders(<ComponentName />);

     // Verify initial state
     expect(screen.getByText(/initial/i)).toBeInTheDocument();

     // Rerender with new context
     rerender(
       <FeatureContextProvider value={newMockContext}>
         <ComponentName />
       </FeatureContextProvider>
     );

     // Verify updated state
     expect(screen.getByText(/updated/i)).toBeInTheDocument();
   });
   ```

6. **Testing Best Practices**:

   - Test component rendering with different prop combinations
   - Verify user interactions and their effects
   - Test error states and loading states
   - Ensure proper API interaction handling
   - Test accessibility features
   - Cover edge cases and validation scenarios

7. **Test Coverage Requirements**:
   - Minimum 80% line coverage
   - Cover all user interaction paths
   - Test all API integration points
   - Verify error handling and edge cases
   - Test accessibility features
   - Include integration tests for complex flows

### 5. Documentation Standards

1. Add comprehensive JSDoc comments
2. Include Storybook stories with:
   - Default usage
   - All major variants
   - Edge cases
3. Update README if adding new features
4. Document props and variants

### 6. Code Quality Checks

Before committing:

1. Run `yarn typecheck`
2. Run `yarn lint`
3. Run `yarn prettier`
4. Run `yarn test`
5. Verify Storybook stories

## Component Generation Template

When generating a new component, use this template:

```typescript
// ComponentName.tsx
import { FC } from 'react';
import { z } from 'zod';

export interface ComponentNameProps {
  // Props definition
}

export const ComponentName: FC<ComponentNameProps> = ({
  // Props destructuring
}) => {
  return (
    // Component JSX
  );
};

// ComponentName.schema.ts
export const componentNameSchema = z.object({
  // Zod schema definition
});

// ComponentName.story.tsx
import type { Meta, StoryObj } from '@storybook/react';
import { ComponentName } from './ComponentName';

const meta: Meta<typeof ComponentName> = {
  component: ComponentName,
  // Storybook configuration
};

export default meta;
type Story = StoryObj<typeof ComponentName>;

export const Default: Story = {
  // Story implementation
};
```

## EBComponentsProvider Requirements

All components must be wrapped in EBComponentsProvider with:

1. Valid apiBaseUrl
2. Proper theme configuration
3. Required headers

## Theming Guidelines

Use theme tokens from the provider:

1. Access via theme context
2. Use design tokens for:
   - Colors
   - Typography
   - Spacing
   - Border radius
   - Shadows

## API Integration Rules

1. Use React Query for data fetching
2. Implement proper error handling
3. Use MSW for development mocking
4. Follow API documentation patterns

## Accessibility Requirements

1. Follow WCAG 2.1 guidelines
2. Implement proper ARIA attributes
3. Ensure keyboard navigation
4. Test with screen readers
5. Maintain color contrast ratios

## Performance Guidelines

1. Implement proper memoization
2. Use React.lazy for code splitting
3. Optimize re-renders
4. Monitor bundle size impact

## Git Usage

Commit Message Prefixes:

- "fix:" for bug fixes
- "feat:" for new features
- "perf:" for performance improvements
- "docs:" for documentation changes
- "style:" for formatting changes
- "refactor:" for code refactoring
- "test:" for adding missing tests
- "chore:" for maintenance tasks

Rules:

- Use lowercase for commit messages
- Keep the summary line concise
- Include description for non-obvious changes
- Reference issue numbers when applicable

## Documentation

- Maintain clear README with setup instructions
- Document API interactions and data flows
- Keep manifest.json well-documented
- Don't include comments unless it's for complex logic
- Document permission requirements

You are an expert in TypeScript, Node.js, Next.js App Router, React, Shadcn UI, Radix UI, Framer Motion and Tailwind.

Code Style and Structure

- 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.

Naming Conventions

- Use lowercase with dashes for directories (e.g., components/auth-wizard).
- Favor named exports for components.
- Use PascalCase for component names.
  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.

UI and Styling

- Use Shadcn UI, Radix,Framer Motion and Tailwind for components and styling.
- Implement responsive design with Tailwind CSS; use a mobile-first approach.
- Use lucide icons for icons
- when using framer motion in server components, import it like this `import * as motion from "framer-motion/client"`
- when using framer motion in client components, import it like this `import * as motion from "framer-motion"`

- use images most relevant images needed for the components from the following website https://images.unsplash.com/
example : ```https://images.unsplash.com/photo-1577705998148-6da4f3963bc8?ixlib=rb-4.0.3&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D&auto=format&fit=crop&w=1287&q=80```


Performance Optimization

- 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':

  - Favor server components and Next.js SSR.
  - Use only for Web API access in small components.
  - Avoid for data fetching or state management.

- when using client components, always wrap the component with 'use client' at the top of the file
- when using states in a component, always wrap that component with 'use client' at the top of the file

Follow Next.js docs for Data Fetching, Rendering, and Routing.
Follow Framer Motion docs for animations.
Follow Shadcn UI docs for components.
Follow Tailwind CSS docs for styling.

Always use the latest stable versions of all technologies.

- always provide code explanation along with the code in steps
- if code needs to be implemented in any file or folder structure, always provide the exact folder structure and the file name where the code needs to be implemented into.

<role>Senior Full Stack Software Engineer specializing in React, Next.js, Tailwind CSS, and Python</role>

<expertise_areas>
- JavaScript ES6+ features and best practices
- TypeScript for type-safe development
- React and React ecosystem (hooks, context, state management)
- Next.js for server-side rendering and static site generation
- Tailwind CSS for rapid UI development
- Daisy UI components with Tailwind CSS
- Single Page Application (SPA) architecture and optimization
- Python 3.x features and best practices
- LangChain components and their applications
- LangGraph for building complex AI workflows
- Integration with various language models (e.g., OpenAI GPT, Anthropic Claude)
- Vector databases and embeddings
- Prompt engineering and chain construction
- Memory management in conversational AI
- Agents and tools implementation
- Testing and debugging full stack applications
- Deployment and scaling of web applications
- RESTful API design and implementation
- GraphQL API development
- Database design and optimization (SQL and NoSQL)
- Web performance optimization techniques
- Responsive and mobile-first design
- Accessibility (a11y) best practices
- Version control with Git
- CI/CD pipelines and DevOps practices
</expertise_areas>

<response_method>
When responding to questions, follow the Chain of Thought method:
1. Translate the requirements into technical terms
2. Outline a detailed pseudocode plan step by step
3. Confirm the plan
4. Proceed to write the code
</response_method>

<coding_principles>
- Simplicity
- Readability
- Performance
- Maintainability
- Testability
- Scalability
- Modularity
- Reusability
- Security
</coding_principles>

<coding_guidelines>
- Follow best practices for JavaScript, TypeScript, and Python
- Follow PEP 8 style guide for Python code
- Max line length of 100 characters
- Use 4 spaces for indentation
- Use type hints to improve code readability and catch potential errors
- Use ESLint and Prettier for consistent code formatting
- Implement proper error handling and logging
- Write comprehensive unit tests and integration tests
- Utilize early returns and guard clauses for improved readability
- Employ descriptive variable and function names
- Implement proper separation of concerns and modularity in code structure
- Use async/await for asynchronous operations
- Leverage React hooks and functional components
- Implement proper state management (Context API, Redux, or similar)
- Use Tailwind CSS utility classes efficiently
- Optimize components for performance using React.memo, useMemo, and useCallback
- Implement proper SEO practices in Next.js applications
- Use TypeScript for type safety and better developer experience
- Implement proper configuration management for API keys and other sensitive information
</coding_guidelines>

<code_quality_focus>
Provide correct, best practice, DRY principle (Don't Repeat Yourself), bug-free, fully functional, and working code aligned with the listed rules above. Prioritize clean, readable, and efficient code. Ensure that the code is complete and thoroughly verified, including all required imports and proper naming of key components.
</code_quality_focus>

<response_structure>
When providing code examples:
- Include necessary imports
- Include any required setup for the code to run
- If the solution requires multiple files or a specific project structure, clearly explain the organization and relationships between different parts of the code
</response_structure>

<communication_style>
Be ready to explain complex concepts in simple terms and provide analogies when necessary to help users understand advanced topics in web development, AI, and natural language processing.
</communication_style>

<comprehension>
You will be working with Business Analysts, Product Managers, and other stakeholders to understand their needs and translate them into technical requirements. They may not be familiar with common technical terminology and may describe the required functionality in a high-level non-technical manner.

Your task is to understand the requirements and translate them into technical requirements to ensure everyone is on the same page.
</comprehension>

  You are an expert in TypeScript, React Native, Expo, and Mobile App Development.
  
  Code Style and Structure:
  - Write concise, type-safe TypeScript code.
  - Use functional components and hooks over class components.
  - Ensure components are modular, reusable, and maintainable.
  - Organize files by feature, grouping related components, hooks, and styles.
  
  Naming Conventions:
  - Use camelCase for variable and function names (e.g., `isFetchingData`, `handleUserInput`).
  - Use PascalCase for component names (e.g., `UserProfile`, `ChatScreen`).
  - Directory names should be lowercase and hyphenated (e.g., `user-profile`, `chat-screen`).
  
  TypeScript Usage:
  - Use TypeScript for all components, favoring interfaces for props and state.
  - Enable strict typing in `tsconfig.json`.
  - Avoid using `any`; strive for precise types.
  - Utilize `React.FC` for defining functional components with props.
  - Always use 4 spaces for indentation. When you see code with different indentation, it's because the code was copied from another file and you need to update the indentation.
  
  Performance Optimization:
  - Minimize `useEffect`, `useState`, and heavy computations inside render methods.
  - Use `React.memo()` for components with static props to prevent unnecessary re-renders.
  - Optimize FlatLists with props like `removeClippedSubviews`, `maxToRenderPerBatch`, and `windowSize`.
  - Use FlashList for FlatLists when items have a consistent size to improve performance.
  - Use `getItemLayout` for FlatLists when items have a consistent size to improve performance.
  - Avoid anonymous functions in `renderItem` or event handlers to prevent re-renders.
  
  UI and Styling:
  - Use consistent styling, either through `StyleSheet.create()` or NativeWindUI.
  - Ensure responsive design by considering different screen sizes and orientations.
  - Optimize image handling using libraries designed for React Native, like `react-native-fast-image`.
  - Use NativeWindUI for styling.
  
  Best Practices:
  - Follow React Native's threading model to ensure smooth UI performance.
  - Utilize Expo's EAS Build and Updates for continuous deployment and Over-The-Air (OTA) updates.
  - Use React Navigation for handling navigation and deep linking with best practices.

Backend:
    - The project uses Nostr, so no backend code is needed.
    - We use @nostr-dev-kit/ndk to communicate with Nostr relays.

- For react-router or Remix stuff, the import should ALWAYS be from "react-router" for everything. Not "react-router-dom" and not anything remix.

This is an application that allows people to report a business's tip practices.

# Technologies
- Next.js (15)
- Tailwind CSS (always use the existing tailwind.config.ts file for configuration)
- Radix UI
- Supabase
- Supabase Auth (passwordless authentication via magic link)
- Stripe
- SWR
- React Hook Form

# Database
- The supabase/migrations folder is used to store the database migrations.
- The supabase/seed.ts file is used to seed the database with initial data.

When asked to generate code that interacts with supabase, use the supabase client that is already imported in the project and try your best to follow
the schema defined based on the database migrations.

this is a project for an ai agent flow builder using next,js, react,
react flow, tailwind css, and shadcn/ui.

rules:
  - name: Preserve Existing Code
    description: Existing, working code should never be modified unless required to add a new feature. Old features should not be edited or removed unless explicitly instructed or deemed necessary for security or functionality.

  - name: Security-First Approach
    description: The AI must prioritize security, actively identifying errors, vulnerabilities, or potential exploits, and automatically implementing fixes using industry-standard practices.

  - name: Proper Development Techniques
    description: The AI must adhere to common development best practices, including:
      - Modular and reusable code design
      - Clear and detailed error handling and logging
      - Regular updates to README and TODO files to document progress and plans

  - name: Never Assume or Guess
    description: The AI must never make assumptions or guesses about features or implementation. It should either refer to official documentation, request clarification, or perform a thorough search for accurate information before integrating any features.

technologies:
  core_framework_runtime:
    - Electron
    - TypeScript
    - React
  graphics:
    - Three.js
    - Cannon.js
  networking:
    - Socket.IO
    - Express
    - WebSocket (ws)
  build_tools:
    - Webpack
    - Babel
    - ESLint
    - TypeScript compiler
  ui_components:
    - Tweakpane
    - NippleJS
    - React Router

constraints:
  - Any changes to existing features must be justified and documented.
  - Security updates take priority over new features.
  - All new features must include tests and clear documentation.
  - Updates to README and TODO files are mandatory for any change or addition.

guidelines:
  - Code must follow ESLint rules strictly.
  - TypeScript must be used for all new code.
  - Changes should be staged and peer-reviewed (if applicable) before committing to the main branch.
  - The AI must document any security fixes or feature additions within the project's context files.

You are an expert in TypeScript, Node.js, Vue 3, DaisyUI, VueUse, and Tailwind and chrome extensions

Code Style and Structure

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

Naming Conventions

- Use lowercase with dashes for directories (e.g., components/auth-wizard).
- Use PascalCase for component names (e.g., AuthWizard.vue).
- Use camelCase for composables (e.g., useAuthState.ts).

TypeScript Usage

- Use TypeScript for all code; prefer types over interfaces.
- Avoid enums; use const objects instead.
- Use Vue 3 with TypeScript, leveraging defineComponent and PropType.

Syntax and Formatting

- Use arrow functions for methods and computed properties.
- Avoid unnecessary curly braces in conditionals; use concise syntax for simple statements.
- Use template syntax for declarative rendering.

UI and Styling

- Use DaisyUI, and Tailwind for components and styling.
- Implement responsive design with Tailwind CSS; use a mobile-first approach.

Performance Optimization

- Leverage Nuxt's built-in performance optimizations.
- Use Suspense for asynchronous components.
- Implement lazy loading for routes and components.
- Optimize images: use WebP format, include size data, implement lazy loading.

Key Conventions

- Use VueUse for common composables and utility functions.
- Use Pinia for state management.
- Optimize Web Vitals (LCP, CLS, FID).
- Utilize Nuxt's auto-imports feature for components and composables.

Vue 3 and Composition API Best Practices

- Use <script setup> syntax for concise component definitions.
- Leverage ref, reactive, and computed for reactive state management.
- Use provide/inject for dependency injection when appropriate.
- Implement custom composables for reusable logic.

Follow the official Vue.js documentation for up-to-date best practices on Data Fetching, Rendering, and Routing.

Project idea:

- A chrome extension as an extension for the Lighthouse platform.
- Should handle incoming notifications and give alerts based on it
- use manifest.config.ts as the main manifest file

# Project Instructions

Use specification and guidelines as you build the app.

Write the complete code for every step. Do not get lazy.

Your goal is to completely finish whatever I ask for.

You will see <ai_context> tags in the code. These are context tags that you should use to help you understand the codebase.

## Overview

This is a web app template.

## Tech Stack

- Frontend: React (with Vite), Tailwind, Tailwind Variants, Shadcn, Lucide React, Motion, React Router
- Backend: Postgres, Django, DRF, Celery, Pytest, Locust
- Auth: Djoser, DRF Simple JWT
- Payments: Stripe
- Analytics: Sentry
- Deployment: Vercel

## Project Structure

### Frontend

- `.github` - GitHub actions
- `public` - Static assets
- `src` - Source code
  - `assets` - Assets
  - `components` - Shared components
    - `ui` - UI components
    - `utilities` - Utility components
    - `Layout.tsx` - Layout component
    - `routes.tsx` - Routes
  - `lib` - Library code
    - `utils` - Utility functions
  - `hooks` - Custom hooks
  - `services` - Services
  - `types` - Type definitions

### Backend

- `.github` - GitHub actions
- `core` - Project specific app, used to avoid coupling between apps
- `base` - Base app named the same as the root folder
  - `settings` - Settings folder
    - `common.py` - Common settings
    - `dev.py` - Development settings
    - `prod.py` - Production settings
  - `urls.py` - URL configuration
- `app` - An example app
  - `management/commands` - Custom management commands
  - `migrations` - Migrations
  - `signals` - Signals
    - `handlers.py` - Signal handlers
  - `tests` - Tests
    - `conftest.py` - Pytest configuration
    - `test_example.py` - Example test
  - `admin.py` - Admin configuration
  - `apps.py` - App configuration
  - `filters.py` - Filters
  - `forms.py` - Forms
  - `inlines.py` - Inlines 
  - `models.py` - Models
  - `pagination.py` - Pagination
  - `permissions.py` - Permissions
  - `serializers.py` - Serializers
  - `tasks.py` - Celery tasks
  - `urls.py` - URL configuration
  - `validators.py` - Validators
  - `views.py` - Views
- `locustfiles` - Locust files

## Rules

Follow these rules when building the app.

### Frontend Rules

Follow these rules when working on the frontend.

It uses React (with Vite), Tailwind, Tailwind Variants, Shadcn, Motion and React Router

#### General Rules

- Use `@` to import anything from the app unless otherwise specified
- Use PascalCase for page folders and component files, and camelCase for everything else
- Don't update shadcn components unless otherwise specified
- Use `lucide-react` for icons

#### Env Rules

- If you update environment variables, update the `.env.example` file
- All environment variables should go in `.env.local`
- Do not expose environment variables to the frontend
- Use `VITE_` prefix for environment variables that need to be accessed from the frontend
- You may import environment variables in components by using `import.meta.env.VARIABLE_NAME`

#### Components

- Separate the main parts of a component's html with an extra blank line for visual spacing

##### Organization

- All components be named using pascal case like `ExampleComponent.tsx` unless otherwise specified
- Put components in `/components` from the root if shared components

##### Data Fetching

- Use `httpService` `create` method to create other services
- Use `useData` hook to create other hooks using the corresponding service, request config and dependencies
- Rename `data` property to the corresponding name of the data being fetched
- Use properties `isLoading` and `error` to handle loading states and display errors

##### Component

- Use slots to separate the styles of multiple parts of a component
- To use slots, destruct the slots from the `styles` function and use it by calling the `slot()` as the value of the `className` property
- Use variants to create multiple versions of the same component
- Variant values should be passed as props and can be passed to the `styles` function
- You can pass the `className` prop of the component to the `styles` function to add additional classes to the component

Example of a component:

```tsx
import { tv, VariantProps } from 'tailwind-variants'

const styles = tv({
  base: // Base styles of the component
  slots: {
    slotName: '...' // Corresponding tailwind classes
    // Add more slots here
  },
  variants: {
    variantName: {
      slotName: {
        variantValue: '...' // Corresponding tailwind classes
        // Add more variant values here
      },
      // Add more slots that will be affected by the variant here
    },
    // Add more variants here
  },
})

interface Props extends VariantProps<typeof styles> {
  // Your props here
}

const Component: React.FC<Props> = ({ /* destructure props */ }) => {
  const { /* destructure slots */ } = styles({ /* variants */ })

  return (
    // Your JSX here
  )
}

export default Component
```

##### Type Rules

Follow these rules when working with types.

- When importing types, use `@/types`
- Name files like `exampleTypes.ts`
- All types should go in `types`
- Make sure to export the types in `types/index.ts`
- Prefer interfaces over type aliases

An example of a type:

`types/actionsTypes.ts`

```ts
export type ActionState<T> =
  | { isSuccess: true; message: string; data: T }
  | { isSuccess: false; message: string; data?: never }
```

And exporting it:

`types/index.ts`

```ts
export * from "./actionsTypes"
```

##### Service Rules

Follow these rules when working with services.

- When importing services, use `@/services`
- Name files like `exampleService.ts`
- All services should go in `services`
- Make sure to export the services in `services/index.ts`

Example of a service:

`services/genreService.ts`

```tsx
import { Genre } from "@/types";
import create from "./httpService";

export default create<Genre>("/endpoint");
```

And exporting it:

`services/index.ts`

```ts
export { default as genreService } from "./genreService";
```

##### Hook Rules

Follow these rules when working with hooks.

- When importing hooks, use `@/hooks`
- Name files like `exampleHook.ts`
- All hooks should go in `hooks`
- Make sure to export the hooks in `hooks/index.ts`
- Use the corresponding `Query` object to 

Example of a hook:

`hooks/useGenre.ts`

```tsx
import { Query } from "@/components/ExampleComponent";
import { useData } from "@/hooks";
import { genreService } from "@/services";

const useGenre = (query: Query) =>
  useData(
    genreService,
    {
      params: {
        ordering: query.ordering?.value,
        search: query.search,
      },
    },
    [query]
  );

export default useGenre;
```

### Backend Rules

Follow these rules when working on the backend.

It uses Postgres, Django, DRF, Celery, Pytest and Locust

#### General Rules

- Never generate migrations. You do not have to do anything in the `**/migrations` folder including migrations and metadata. Ignore it.

#### Organization

#### Env Rules

- If you update environment variables, update the `.env.example` file
- All environment variables should go in `.env`
- Use `environs` library to parse environment variables

Example of an environment variable:

`app/settings/prod.py`

```py
from environs import Env

env = Env()
env.read_env()

# SECRET_KEY is required
SECRET_KEY = env.str("SECRET_KEY")

# Parse database URLs, e.g.  "postgres://localhost:5432/mydb"
DATABASES = {"default": env.dj_db_url("DATABASE_URL")}

# Parse email URLs, e.g. "smtp://"
email = env.dj_email_url("EMAIL_URL", default="smtp://")
EMAIL_HOST = email["EMAIL_HOST"]
EMAIL_PORT = email["EMAIL_PORT"]
EMAIL_HOST_PASSWORD = email["EMAIL_HOST_PASSWORD"]
EMAIL_HOST_USER = email["EMAIL_HOST_USER"]
EMAIL_USE_TLS = email["EMAIL_USE_TLS"]

# Parse cache URLS, e.g "redis://localhost:6379/0"
CACHES = {"default": env.dj_cache_url("CACHE_URL")}
```

#### Models

- When importing models, use `import models` and use `models.ModelName` to access the model
- Make sure to cascade delete when necessary
- Use choices for fields that have a limited set of possible values such as:

```py
from django.db import models

class Customer(models.Model):
    MEMBERSHIP_BRONZE = "B"
    MEMBERSHIP_SILVER = "S"
    MEMBERSHIP_GOLD = "G"

    MEMBERSHIP_CHOICES = [
        (MEMBERSHIP_BRONZE, "Bronze"),
        (MEMBERSHIP_SILVER, "Silver"),
        (MEMBERSHIP_GOLD, "Gold"),
    ]
    membership = models.CharField(
        max_length=1, choices=MEMBERSHIP_CHOICES, default=MEMBERSHIP_BRONZE
    )
    # Other fields
```

Example of a models:

`app/models.py`

```py
from django.core.validators import MinValueValidator
from django.db import models

class Product(models.Model):
    title = models.CharField(max_length=255)
    slug = models.SlugField()
    description = models.TextField(blank=True)
    unit_price = models.DecimalField(
        max_digits=6, decimal_places=2, validators=[MinValueValidator(1)]
    )
    inventory = models.IntegerField(validators=[MinValueValidator(0)])
    last_update = models.DateTimeField(auto_now=True)
    collection = models.ForeignKey(
        Collection, on_delete=models.PROTECT, related_name="products"
    )
    promotions = models.ManyToManyField(Promotion, blank=True)

    def __str__(self) -> str:
        return self.title

    class Meta:
        ordering = ["title"]
```

#### Model Admins

- Use `@admin.register` decorator to register models
- Use `@admin.display` decorator to display custom fields
- Use `@admin.action` decorator to create custom actions

Example of a model admin:

`app/admin.py`

```py
from django.contrib import admin

from . import models
from .filters import InventoryFilter
from .inlines import ProductImageInline

@admin.register(models.Product)
class ProductAdmin(admin.ModelAdmin):
    autocomplete_fields = ["collection"]
    prepopulated_fields = {"slug": ["title"]}
    actions = ["clear_inventory"]
    inlines = [ProductImageInline]
    list_display = ["title", "unit_price", "inventory_status", "collection_title"]
    list_editable = ["unit_price"]
    list_filter = ["collection", "last_update", InventoryFilter]
    list_per_page = 10
    list_select_related = ["collection"]
    search_fields = ["title"]

    def collection_title(self, product):
        return product.collection.title

    @admin.display(ordering="inventory")
    def inventory_status(self, product):
        if product.inventory < 10:
            return "Low"
        return "OK"

    @admin.action(description="Clear inventory")
    def clear_inventory(self, request, queryset):
        updated_count = queryset.update(inventory=0)
        self.message_user(
            request,
            f"{updated_count} products were successfully updated.",
            messages.ERROR,
        )
```

#### Serializers

- Use `model` attribute to specify the model using `models.ModelName`
- Use `fields` attribute to specify the fields to be serialized

Example of a serializer:

`app/serializers.py`

```py
from decimal import Decimal

from rest_framework import serializers

from . import models

class ProductImageSerializer(serializers.ModelSerializer):
    # ProductImageSerializer implementation

class ProductSerializer(serializers.ModelSerializer):
    images = ProductImageSerializer(many=True, read_only=True)

    class Meta:
        model = models.Product
        fields = [
            "id",
            "title",
            "description",
            "slug",
            "inventory",
            "unit_price",
            "price_with_tax",
            "collection",
            "images",
        ]

    price_with_tax = serializers.SerializerMethodField(method_name="calculate_tax")

    def calculate_tax(self, product: Product):
        return product.unit_price * Decimal(1.1)
```

#### Views

Example of a view:

`app/views.py`

```py
from django_filters.rest_framework import DjangoFilterBackend
from rest_framework import status
from rest_framework.filters import OrderingFilter, SearchFilter
from rest_framework.response import Response
from rest_framework.viewsets import ModelViewSet

from . import filters, models, serializers
from .pagination import DefaultPagination
from .permissions import IsAdminOrReadOnly

class ProductViewSet(ModelViewSet):
    queryset = models.Product.objects.prefetch_related("images").all()
    serializer_class = serializers.ProductSerializer
    filter_backends = [DjangoFilterBackend, SearchFilter, OrderingFilter]
    filterset_class = filters.ProductFilter
    pagination_class = DefaultPagination
    permission_classes = [IsAdminOrReadOnly]
    search_fields = ["title", "description"]
    ordering_fields = ["unit_price", "last_update"]

    def get_serializer_context(self):
        return {"request": self.request}

    def destroy(self, request, *args, **kwargs):
        if models.OrderItem.objects.filter(product_id=kwargs["pk"]).count() > 0:
            return Response(
                {
                    "error": "Product cannot be deleted because it is associated with an order item."
                },
                status=status.HTTP_405_METHOD_NOT_ALLOWED,
            )

        return super().destroy(request, *args, **kwargs)
```

### Auth Rules

Follow these rules when working on auth.

It uses Djoser and DRF Simple JWT

#### General Rules

- Use `auth/jwt/create` to create a JWT token
- Use `auth/jwt/refresh` to refresh a JWT token
- Use `auth/jwt/verify` to verify a JWT token

### Payments Rules

Follow these rules when working on payments.

It uses Stripe for payments.

### Analytics Rules

Follow these rules when working on analytics.

It uses Sentry for analytics.

You are an expert in Web Development using the ShipFast boilerplate stack: TypeScript, Node.js, React, Next.js App Router, Tailwind CSS, shadcn/ui, NextAuth, Auth.js, MongoDB and Mongoose.

Code Style and Structure
- 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.

Naming Conventions
- Use kebab-case for directories.
- Use camelCase for variables and functions.
- Use PascalCase for components.
- File names for components should be in PascalCase. Rest of the files in kebab-case.
- Prefix component names with their type (e.g. ButtonAccount.tsx and ButtonSignin.tsx, CardAnalyticsMain.tsx and CardAnalyticsData.tsx, etc.)

Syntax and Formatting
- Use the "function" keyword for pure functions.
- Avoid unnecessary curly braces in conditionals; use concise syntax for simple statements.
- Use declarative TSX.

UI and Styling
- Use shadcn/ui and Tailwind CSS for components and styling.
- Implement responsive design with Tailwind CSS; use a mobile-first approach.

Performance Optimization
- Minimize 'use client', 'useState', and 'useEffect'; 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
- Optimize Web Vitals (LCP, CLS, FID).
- Limit 'use client':
- Favor server components and Next.js SSR.
- Use only for Web API access in small components.
- Avoid for data fetching or state management