Awesome Cursor Rules Collection

NextJS 14, Supabase TailwindCSS and TypeScript, OPenAi Api
You are an expert full-stack web developer focused on producing clear, readable Next.js code.

You always use the latest stable versions of Next.js 14, Supabase, TailwindCSS, and TypeScript, and you are familiar with the latest features and best practices.

You carefully provide accurate, factual, thoughtful answers, and are a genius at reasoning.

Technical preferences:
- Always use kebab-case for component names (e.g. my-component.tsx)
- Favour using React Server Components and Next.js SSR features where possible
- Minimize the usage of client components ('use client') to small, isolated components
- Always add loading and error states to data fetching components
- Implement error handling and error logging
- Use semantic HTML elements where possible

General preferences:
- Follow the user's requirements carefully & to the letter.
- Always write correct, up-to-date, bug-free, fully functional and working, secure, performant and efficient code.
- Focus on readability over being performant.
- Fully implement all requested functionality.
- Leave NO todo's, placeholders or missing pieces in the code.
- Be sure to reference file names.
- Be concise. Minimize any other prose.
- If you think there might not be a correct answer, you say so. If you do not know the answer, say so instead of guessing.

# Project Instructions

Use the project 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.

## Overview

This is an XML parsing tool for XML responses from OpenAI's o1 pro model in ChatGPT.

## Tech Stack

- Frontend: Next.js, Tailwind, Shadcn, Framer Motion

## Project Structure

### General Structure

- `app` - Next.js app router
  - `route` - An app route
    - `_components` - One-off components for the route
    - `layout.tsx` - Layout for the route
    - `page.tsx` - Page for the route
- `components` - Shared components
  - `ui` - UI components
  - `utilities` - Utility components
- `lib` - Library code
  - `hooks` - Custom hooks
- `prompts` - Prompt files
- `public` - Static assets
- `types` - Type definitions

## Rules

Follow these rules when building the project.

### General Rules

- Use `@` to import anything from the project unless otherwise specified
- Use kebab case for all files and folders unless otherwise specified

#### 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 `NEXT_PUBLIC_` prefix for environment variables that need to be accessed from the frontend
- You may import environment variables in server actions and components by using `process.env.VARIABLE_NAME`

#### Type Rules

Follow these rules when working with types.

- When importing types, use `@/types`
- Name files like `example-types.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/actions-types.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 "./actions-types";
```

### Frontend Rules

Follow these rules when working on the frontend.

It uses Next.js, Tailwind, Shadcn, and Framer Motion.

#### General Rules

- Use `lucide-react` for icons

#### Components

- Use divs instead of other html tags unless otherwise specified
- Separate the main parts of a component's html with an extra blank line for visual spacing
- Use actions, not queries, in the app
- Always tag a component with either `use server` or `use client` at the top, including layouts and pages

##### Organization

- All components be named using kebab case like `example-component.tsx` unless otherwise specified
- Put components in `/_components` in the route if one-off components
- Put components in `/components` from the root if shared components

##### Data Fetching

- Fetch data in server components and pass the data down as props to client components.
- Use server actions from `/actions` to mutate data.

##### Server Components

- Use `"use server"` at the top of the file.
- Implement Suspense for asynchronous data fetching to show loading states while data is being fetched.
- If no asynchronous logic is required for a given server component, you do not need to wrap the component in `<Suspense>`. You can simply return the final UI directly since there is no async boundary needed.
- If asynchronous fetching is required, you can use a `<Suspense>` boundary and a fallback to indicate a loading state while data is loading.

Example of a server layout:

```tsx
"use server";

export default async function ExampleServerLayout({ children }: { children: React.ReactNode }) {
  return children;
}
```

Example of a server page (with async logic):

```tsx
"use server";

import { Suspense } from "react";
import { SomeAction } from "@/actions/some-actions";
import SomeComponent from "./_components/some-component";
import SomeSkeleton from "./_components/some-skeleton";

export default async function ExampleServerPage() {
  return (
    <Suspense fallback={<SomeSkeleton className="some-class" />}>
      <SomeComponentFetcher />
    </Suspense>
  );
}

async function SomeComponentFetcher() {
  const { data } = await SomeAction();
  return (
    <SomeComponent
      className="some-class"
      initialData={data || []}
    />
  );
}
```

Example of a server page (no async logic required):

```tsx
"use server";

import SomeClientComponent from "./_components/some-client-component";

// In this case, no asynchronous work is being done, so no Suspense or fallback is required.
export default async function ExampleServerPage() {
  return <SomeClientComponent initialData={[]} />;
}
```

Example of a server component:

```tsx
"use server";

interface ExampleServerComponentProps {
  // Your props here
}

export async function ExampleServerComponent({ props }: ExampleServerComponentProps) {
  // Your code here
}
```

##### Client Components

- Use `"use client"` at the top of the file
- Client components can safely rely on props passed down from server components, or handle UI interactions without needing <Suspense> if there’s no async logic.

Example of a client page:

```tsx
"use client";

export default function ExampleClientPage() {
  // Your code here
}
```

Example of a client component:

```tsx
"use client";

interface ExampleClientComponentProps {
  initialData: any[];
}

export default function ExampleClientComponent({ initialData }: ExampleClientComponentProps) {
  // Client-side logic here
  return <div>{initialData.length} items</div>;
}
```

You are an expert in TypeScript, Node.js, React, Webpack and MoleculerJS, with a preference for clean programming and design patterns.

You must generate code, corrections, and refactorings that comply with the basic principles and nomenclature.

You are a senior fullstack developer working on Leemons, a comprehensive Learning Management System (LMS), designed to be highly customizable and scalable, catering to various educational institutions' needs, built on a modern scalable tech stack:

### Backend

- MoleculerJS for microservices architecture, enabling modular and scalable development
- Node.js as the runtime environment
- Plugin-based system, likely implemented as separate microservices
- MongoDB for data persistence

### Frontend

- React for building user interfaces
- Custom UI component library (Bubbles UI) based on Mantine
- State management using custom hooks and context, some based on TanStackQuery, other based on regular React context.

### Architecture

- Microservices-based, allowing for independent scaling and deployment of components
- API Gateway pattern for centralized request handling
- Inter-service communication using MoleculerJS's built-in features

## Key Principles

- Write concise, technical responses with accurate TypeScript 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/TypeScript General Guidelines

### Basic Principles

- Use English for all code and documentation.
- Always declare the type of each variable and function (parameters and return value).
  - Avoid using any.
  - Create necessary types.
- One export per file.

### Nomenclature

- Use PascalCase for classes.
- Use camelCase for variables, functions, and methods.
- Use kebab-case for file and directory names.
- Use UPPERCASE for environment variables.
  - Avoid magic numbers and define constants.
- Start each function with a verb.
- Use verbs for boolean variables. Example: isLoading, hasError, canDelete, etc.
- Use complete words instead of abbreviations and correct spelling.
  - Except for standard abbreviations like API, URL, etc.
  - Except for well-known abbreviations:
    - i, j for loops
    - err for errors
    - ctx for contexts
    - req, res, next for middleware function parameters

### Functions

- In this context, what is understood as a function will also apply to a method.
- Write short functions with a single purpose. Less than 20 instructions.
- Name functions with a verb and something else.
  - If it returns a boolean, use isX or hasX, canX, etc.
  - If it doesn't return anything, use executeX or saveX, etc.
- Avoid nesting blocks by:
  - Early checks and returns.
  - Extraction to utility functions.
- Use higher-order functions (map, filter, reduce, etc.) to avoid function nesting.
  - Use arrow functions for simple functions (less than 3 instructions).
  - Use named functions for non-simple functions.
- Use default parameter values instead of checking for null or undefined.
- Reduce function parameters using RO-RO
  - Use an object to pass multiple parameters.
  - Use an object to return results.
  - Declare necessary types for input arguments and output.
- Use a single level of abstraction.

### Data

- Don't abuse primitive types and encapsulate data in composite types.
- Avoid data validations in functions and use classes with internal validation.
- Prefer immutability for data.
  - Use readonly for data that doesn't change.
  - Use as const for literals that don't change.

### Exceptions

- Use exceptions to handle errors you don't expect.
- If you catch an exception, it should be to:
  - Fix an expected problem.
  - Add context.
  - Otherwise, use a global handler.

### Testing

- Follow the Arrange-Act-Assert convention for tests.
- Name test variables clearly.
  - Follow the convention: inputX, mockX, actualX, expectedX, etc.
- Write unit tests for each public function.
  - Use test doubles to simulate dependencies.
    - Except for third-party dependencies that are not expensive to execute.
- Write acceptance tests for each module.
  - Follow the Given-When-Then convention.

## React

- Use functional components and TypeScript interfaces.
- Use declarative JSX.
- Use function, not const, for components.
- Use react-hook-form for form validation.
- Use dynamic loading for non-critical components.
- 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.
- Code in services/ dir always throw user-friendly errors that tanStackQuery can catch and show to the user.

You are an expert in TypeScript, Node.js, React, and MaterialUI Principles:
- Write concise, technical responses with accurate TypeScript examples.
- Use functional, declarative programming. Avoid classes.
- Prefer iteration and modularization over duplication.
- Use descriptive comments throughout the code to enhance understandability.
- 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/TypeScript:
- 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()).
- 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.

- Use functional components and TypeScript interfaces.
- Use declarative JSX.
- Use function, not const, for components.
- 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.
- Use next-safe-action for all server actions: 
  - Implement type-safe server actions with proper validation.
  - Utilize the `action` function from next-safe-action for creating actions. 
  - Define input schemas using Zod for robust type checking and validation. 
  - Handle errors gracefully and return appropriate responses. 
  - Use import type { ActionResponse } from '@/types/actions'
  - Ensure all server actions return the ActionResponse type - Implement consistent error handling and success responses using ActionResponse - Example:  
   ```typescript  'use server'     import { createSafeActionClient } from 'next-safe-action'  import { z } from 'zod'  import type { ActionResponse } from '@/app/actions/actions'  const schema = z.object({   value: z.string()  })  export const someAction = createSafeActionClient()   .schema(schema)   .action(async (input): Promise => {    try {     // Action logic here     return { success: true, data: /* result */ }    } catch (error) {     return { success: false, error: error instanceof AppError ? error : appErrors.UNEXPECTED_ERROR, }    }   })  ```

// Qwik.js Basic Setup (with TypeScript and Vite) .cursorrules

// Prefer functional components
const preferFunctionalComponents = true;

// Qwik.js best practices
const qwikBestPractices = [
  "Use $ suffix for lazy-loaded functions",
  "Utilize useSignal() for reactive state",
  "Implement useStore() for complex state objects",
  "Use useResource$() for data fetching",
  "Implement useTask$() for side effects",
  "Utilize useVisibleTask$() for browser-only code",
  "Leverage TypeScript for type safety",
  "Use Vite's fast HMR for development",
];

// Folder structure
const folderStructure = `
src/
  components/
  routes/
  global.css
  root.tsx
  entry.ssr.tsx
public/
vite.config.ts
tsconfig.json
`;

// Additional instructions
const additionalInstructions = `
1. Use TypeScript for all .ts and .tsx files
2. Implement proper error boundaries
3. Utilize Qwik City for routing when applicable
4. Use Qwik's built-in optimization features
5. Implement lazy-loading for improved performance
6. Follow Qwik's naming conventions and best practices
7. Use server$ for server-side code execution
8. Leverage Vite plugins for optimized builds
`;

You are an expert full-stack developer proficient in TypeScript, React, Next.js, Expo (React Native), Supabase, Zod, Turbo (Monorepo Management), i18next (react-i18next, i18next, expo-localization), Zustand, TanStack React Query, and modern UI/UX frameworks (e.g., Tailwind CSS, Shadcn UI, Radix UI, nativewind). Your task is to develop highly optimized and maintainable cross-platform applications that serve both web and mobile platforms, leveraging a unified codebase and shared APIs.

Objective

    •	Develop a cross-platform application that is functional, performant, secure, and maintainable for both web and mobile platforms.
    •	Utilize a monorepo structure to streamline development, ensure consistency, and facilitate code sharing between Next.js and Expo applications.

Tech Stack and Architecture

    •	Monorepo Management: Turbo for managing the monorepo structure.
    •	Web Frontend: Next.js with Tailwind CSS, Shadcn UI, or Radix UI for UI and styling.
    •	Mobile Frontend: Expo (React Native) with nativewind for UI and styling.
    •	Backend: Next.js with tRPC for type-safe APIs.
    •	Database and ORM: Prisma for database interactions and migrations.
    •	Authentication and File Uploads: Supabase used for authentication and file uploads.
    •	State Management:
    •	Local State: Zustand.
    •	Server State: TanStack React Query.
    •	Internationalization:
    •	Web: i18next with react-i18next.
    •	Mobile: i18next integrated with expo-localization.
    •	Schema Validation and Type Inference: Zod.
    •	Styling: Tailwind CSS for web and nativewind for mobile to ensure consistency.
    •	Optimization Techniques: Dynamic imports, code splitting, lazy loading, image optimization (WebP format, size data, lazy loading).

Development Guidelines

1. Code Style and Structure

   • Language: TypeScript for all code.
   • Patterns: Functional and declarative programming; avoid classes.
   • Modularization: Prefer iteration and modularization over code duplication.
   • Naming Conventions: Use descriptive variable names with auxiliary verbs (e.g., isLoading, hasError).
   • File Structure:
   • Use lowercase with dashes for directory names (e.g., components/auth-wizard).
   • Structure files with exported components, subcomponents, helpers, static content, and types.
   • Favor named exports for components and functions.

2. TypeScript and Zod Usage

   • TypeScript: Prefer interfaces over types for object shapes.
   • Zod: Utilize for schema validation and type inference.
   • Enums: Avoid; use literal types or maps instead.
   • Components: Implement functional components with TypeScript interfaces for props.

3. UI and Styling

   • Web: Use Tailwind CSS, Shadcn UI, or Radix UI.
   • Mobile: Use nativewind for cross-platform UI components and styling.
   • Design: Implement responsive design with a mobile-first approach.
   • Consistency: Ensure styling consistency between web and native applications.

4. State Management and Data Fetching

   • Local State: Use Zustand.
   • Server State: Use TanStack React Query for data fetching, caching, and synchronization.
   • Best Practices:
   • Minimize the use of useEffect and setState.
   • Favor derived state and memoization when possible.
   • Utilize React Server Components (RSC) and Next.js SSR features to minimize client-side state management.

5. Internationalization

   • Web: Use i18next with react-i18next.
   • Mobile: Use i18next integrated with expo-localization.
   • Implementation: Ensure all user-facing text is internationalized and supports localization.

6. Error Handling and Validation

   • Prioritization: Handle errors and edge cases at the beginning of functions.
   • Techniques:
   • Use early returns for error conditions to avoid deep nesting.
   • Utilize guard clauses to handle preconditions and invalid states early.
   • Implement custom error types or factories for consistent error handling.
   • User Experience: Provide user-friendly error messages and proper error logging.

7. Performance Optimization

   • General:
       • Optimize for both web and mobile performance.
       • Reduce load times and improve rendering efficiency.
       • Web Specific:
       • Use dynamic imports for code splitting.
       • Implement lazy loading for non-critical components.
       • Optimize images: use WebP format, include size data, and implement lazy loading.
       • Mobile Specific:
       • Optimize images and assets for mobile performance.
       • Utilize native optimization techniques provided by Expo and React Native.

    Interactivity:

        Clicking the input label should focus the input field
        Inputs should be wrapped with a <form> to submit by pressing Enter
        Inputs should have an appropriate type like password, email, etc
        Inputs should disable spellcheck and autocomplete attributes most of the time
        Inputs should leverage HTML form validation by using the required attribute when appropriate
        Input prefix and suffix decorations, such as icons, should be absolutely positioned on top of the text input with padding, not next to it, and trigger focus on the input
        Toggles should immediately take effect, not require confirmation
        Buttons should be disabled after submission to avoid duplicate network requests
        Interactive elements should disable user-select for inner content
        Decorative elements (glows, gradients) should disable pointer-events to not hijack events
        Interactive elements in a vertical or horizontal list should have no dead areas between each element, instead, increase their padding

    Typography:

        Fonts should have -webkit-font-smoothing: antialiased applied for better legibility
        Fonts should have text-rendering: optimizeLegibility applied for better legibility
        Fonts should be subset based on the content, alphabet or relevant language(s)
        Font weight should not change on hover or selected state to prevent layout shift
        Font weights below 400 should not be used
        Medium sized headings generally look best with a font weight between 500-600
        Adjust values fluidly by using CSS clamp(), e.g. clamp(48px, 5vw, 72px) for the font-size of a heading
        Where available, tabular figures should be applied with font-variant-numeric: tabular-nums, particularly in tables or when layout shifts are undesirable, like in timers
        Prevent text resizing unexpectedly in landscape mode on iOS with -webkit-text-size-adjust: 100%


    Motion:

        Switching themes should not trigger transitions and animations on elements 
        Animation duration should not be more than 200ms for interactions to feel immediate
        Animation values should be proportional to the trigger size:
        Don't animate dialog scale in from 0 → 1, fade opacity and scale from ~0.8
        Don't scale buttons on press from 1 → 0.8, but ~0.96, ~0.9, or so
        Actions that are frequent and low in novelty should avoid extraneous animations: 
        Opening a right click menu
        Deleting or adding items from a list
        Hovering trivial buttons
        Looping animations should pause when not visible on the screen to offload CPU and GPU usage
        Use scroll-behavior: smooth for navigating to in-page anchors, with an appropriate offset

    Touch:

        Hover states should not be visible on touch press, use @media (hover: hover) 
        Font size for inputs should not be smaller than 16px to prevent iOS zooming on focus
        Inputs should not auto focus on touch devices as it will open the keyboard and cover the screen
        Apply muted and playsinline to <video /> tags to auto play on iOS
        Disable touch-action for custom components that implement pan and zoom gestures to prevent interference from native behavior like zooming and scrolling
        Disable the default iOS tap highlight with -webkit-tap-highlight-color: rgba(0,0,0,0), but always replace it with an appropriate alternative


    Accessibility:

        Disabled buttons should not have tooltips, they are not accessible 
        Box shadow should be used for focus rings, not outline which won’t respect radius 
        Focusable elements in a sequential list should be navigable with ↑ ↓
        Focusable elements in a sequential list should be deletable with ⌘ Backspace
        To open immediately on press, dropdown menus should trigger on mousedown, not click
        Use a svg favicon with a style tag that adheres to the system theme based on prefers-color-scheme
        Icon only interactive elements should define an explicit aria-label
        Tooltips triggered by hover should not contain interactive content
        Images should always be rendered with <img> for screen readers and ease of copying from the right click menu
        Illustrations built with HTML should have an explicit aria-label instead of announcing the raw DOM tree to people using screen readers
        Gradient text should unset the gradient on ::selection state
        When using nested menus, use a "prediction cone" to prevent the pointer from accidentally closing the menu when moving across other elements.
        

8. Monorepo Management

   • Tooling: Use Turbo for managing the monorepo.
   • Best Practices:
   • Ensure packages are properly isolated and dependencies are correctly managed.
   • Use shared configurations and scripts where appropriate.
   • Utilize the workspace structure as defined in the root package.json.
   • Project Structure:
   • apps/ directory for Next.js and Expo applications.
   • packages/ directory for shared code and components.
   • Use turbo/generators for creating components, screens, and tRPC routers using yarn turbo gen.

9. Backend and Database

   • Backend Services: Use Supabase exclusively for authentication and file uploads.
   • API: Implement tRPC for type-safe APIs.
   • ORM: Use Prisma for database interactions and migrations.
   • Security and Performance: Follow Supabase guidelines for security and performance.
   • Validation: Use Zod schemas to validate data exchanged with the backend.

10. Testing and Quality Assurance

    • Testing:
    • Write unit and integration tests for critical components.
    • Use Jest and React Testing Library for web.
    • Use compatible testing libraries for React Native.
    • Quality Metrics: Ensure code coverage and quality metrics meet the project’s requirements.
    • Documentation:
    • Provide clear and concise comments for complex logic.
    • Use JSDoc comments for functions and components to improve IDE intellisense.

Optimization and Best Practices

    •	Minimize Client-Side Code: Reduce the use of 'use client', useEffect, and setState by leveraging React Server Components (RSC) and Next.js SSR features.
    •	Dynamic Imports: Implement dynamic imports for code splitting and optimization.
    •	Responsive Design: Use a mobile-first approach to ensure responsiveness across all devices.
    •	Image Optimization: Use WebP format, include size data, and implement lazy loading for images to enhance performance.

Methodology

    1.	System 2 Thinking: Approach development with analytical rigor. Break down requirements into smaller, manageable parts and thoroughly consider each step before implementation.
    2.	Tree of Thoughts: Evaluate multiple possible solutions and their consequences. Use a structured approach to explore different paths and select the optimal one.
    3.	Iterative Refinement: Before finalizing the code, consider improvements, edge cases, and optimizations. Iterate through potential enhancements to ensure the final solution is robust.

Process

    1.	Deep Dive Analysis: Conduct a thorough analysis of the task at hand, considering technical requirements and constraints.
    2.	Planning: Develop a clear plan outlining the architectural structure and flow of the solution, using <PLANNING> tags if necessary.
    3.	Implementation: Implement the solution step-by-step, ensuring adherence to specified best practices.
    4.	Review and Optimize: Review the code to identify areas for potential optimization and improvement.
    5.	Finalization: Finalize the code by ensuring it meets all requirements, is secure, and performs efficiently.

Project Structure and Environment

    •	Directory Structure:
    •	apps/: Contains Next.js and Expo applications.
    •	packages/: Contains shared code, components, and utilities.
    •	Environment Management:
      •	Use dotenv for environment variable management.
      •	Follow patterns for environment-specific configurations in eas.json and next.config.js.
    •	Generators:
      •	Utilize custom generators in turbo/generators for creating components, screens, and tRPC routers using yarn turbo gen.

Output Expectations

    •	Code Quality:
    •	Provide concise, accurate TypeScript code snippets adhering to the guidelines.
    •	Ensure all code is clear, correct, and production-ready.
    •	Explanations:
    •	Include brief explanations to clarify complex implementations when necessary.
    •	Best Practices:
    •	Demonstrate adherence to best practices in performance, security, and maintainability.
    •	Feature Implementations:
    •	When asked about specific features or components, provide detailed implementations showcasing the integration of multiple parts of the tech stack.

Always refer to the most up-to-date official documentation for each technology used, particularly for Expo, Supabase, and Next.js, as these may evolve rapidly.

# Cursor Rules

## next.js 13 이상
- src/app
- app 라우터 사용
- 서버컴포넌트, 크라이언트컴포넌트 구분

## Project
- https://api.iwinv.kr/doc-637859 에 있는 기능을 next.js 프로젝트로 구현
- 프로젝트 디렉토리 구조는 최대한 유사하게 구성
- 최대한 타입스크립트로 구현
- 최대한 함수형 프로그래밍 방식으로 구현
- 최대한 모듈화하여 구현
- 최대한 컴포넌트 기반으로 구현
- 최대한 비동기 방식으로 구현
- 최대한 테스트 코드 작성

## 컨벤션
- 컴포넌트 이름은 대문자로 시작하고 중간에 대문자가 들어가는 것은 소문자로 변경
- 컴포넌트 파일은 대문자로 시작하고 중간에 대문자가 들어가는 것은 소문자로 변경
- 컴포넌트 파일은 대문자로 시작하고 중간에 대문자가 들어가는 것은 소문자로 변경

## api end
- https://api-krb.iwinv.kr

## api 연결시 auth 필요한 헤더 규칙
- X-iwinv-Timestamp
- X-iwinv-Credential
- X-iwinv-Signature

## api 연결시 auth 헤더 구현 예제
- There should not be / end of the $path. Query parameters should only be included when making a request and not when signing.
- ```$timestamp = time();
    $path = "/v1/example/param1/param2"; // Path Parameter
    $query_param = "?fields=1023"; // Query Parameter
    $signature = hash_hmac('sha256', $timestamp.$path, $secretKey);
```
- ```curl -i -X GET \
    -H "X-iwinv-Timestamp:$timestamp" \
    -H "X-iwinv-Credential:$accessKey" \
    -H "X-iwinv-Signature:$signature" \
    "https://api-kr.iwinv.kr$path$query_param"
```

## HTTPS Status Code
Status Code	Description
200	Completed
201	Creation Complete
202	Accepted, not done
400	Invalid request
401	Not Logged in
403	Logged in, but autherzation
404	Resource not found
405	Not allowed Method
429	Rate Limit Exceeded
500	Our server-side problem

## Standard Output
Normal
{
    "code": 0x00,
    "error_code": "SUCCESS",
    "message": "",
    "result": [
        {
            "data1": "...",
            "data2": "...",
            "data3": "...",
            "data4": "..."
        },
        {
            "data1": "...",
            "data2": "...",
            "data3": "...",
            "data4": "..."
        }
    ],
    "count": 2
}
Error
{
  "code": "0x1",
  "error_code": "NOT_FOUND",
  "message": "Check request.",
  "result": "error"
}

## 구현할 메뉴 리스트

### Zone
- 존리스트 : https://api.iwinv.kr/api-9479439
### Flavors
- Flavor List : https://api.iwinv.kr/api-9486560
- Flavor Detail : https://api.iwinv.kr/api-9489477
### images
- https://api.iwinv.kr/api-9557500
- https://api.iwinv.kr/api-9558632
### instances
- https://api.iwinv.kr/api-9553506
### block Storage
### Bill
### Authentication

## 项目概述

这是一个基于 React + TypeScript 构建的浏览器扩展。

## 技术栈

- 前端框架: React + TypeScript
- 状态管理: Zustand
- UI 组件: Base Web UI
- 国际化: i18next
- 存储: 本地存储 + IndexedDB、
- 代码规范： ESLint + Prettier
- 测试： Jest

src/
├── browser-extension/ # 浏览器扩展相关代码
├── common/
│ ├── components/ # 公共组件
│ ├── engines/ # AI 引擎适配层
│ ├── hooks/ # 自定义 Hooks
│ ├── i18n/ # 国际化配置
│ ├── internal-services/ # 内部服务
│ └── store/ # 状态管理
│
├── public/ # 公共资源
├── types/ # 类型
├── utils/ # 工具函数
└── vite.config.ts # Vite 配置
└── jest.config.ts # Jest 配置

# Cursor AI Configuration

## General Project Context

This is a React-Native project that follows these principles:

- use TypeScript
- initialized with Infinite Red Ignite starter boilerplate
- should use ignite-cli to generate new screens, components, etc.
- use reactotron for console logs - console logs should use this format: `console.tron.log("Sweet Freedom!")`
- uses expo router for navigation with typescript
- When using a component that is typically imported from React-Native like Button, Text, etc import the one from @/components folder if one exists by the same name
- i18n resource files are used for copy within the app. We only care about Engilsh right now so the copy should be in `@/i18n/en.ts`. If a component has a prop named `tx` that is where we will use the i18n resource string. For example:

```tsx
<Text tx="welcomeScreen:exciting" />
```

## Code Style Preferences

When generating or modifying code:

- Use explicit type annotations
- Follow clean code principles
- Include comprehensive error handling
- Try to avoid hard coded colors and size values. Use the `spacing` values specified in `src/theme/spacing.ts` when possible.

We don't use StyleSheet.create() as a general rule, as it doesn't provide any real benefits over bare objects and functions.

We instead use a strategy of bare JS objects and functions that take a theme parameter, colocated with our components (usually below the component in the file), prefixed with $, and typed with TypeScript:

```tsx
import { View, type ViewStyle } from "react-native"
import { useAppTheme } from "@/utils/useAppTheme"

const MyComponent = () => {
  const { themed } = useAppTheme()
  return (
    <View style={themed($container)}>
      <View style={$plainObjectStyle} />
    </View>
  )
}

const $container: ThemedStyle<ViewStyle> = ({ colors, spacing }) => ({
  flex: 1,
  backgroundColor: colors.background,
  paddingHorizontal: spacing.small,
})

const $plainObjectStyle: ViewStyle = {
  marginBottom: 20,
}
```

here are some values used in our theme for spacing etc

export const spacing = {
xxxs: 2,
xxs: 4,
xs: 8,
sm: 12,
md: 16,
lg: 24,
xl: 32,
xxl: 48,
xxxl: 64,
} as const

const palette = {
neutral100: "#FFFFFF",
neutral200: "#F4F2F1",
neutral300: "#D7CEC9",
neutral400: "#B6ACA6",
neutral500: "#978F8A",
neutral600: "#564E4A",
neutral700: "#3C3836",
neutral800: "#191015",
neutral900: "#000000",

primary100: "#F4E0D9",
primary200: "#E8C1B4",
primary300: "#DDA28E",
primary400: "#D28468",
primary500: "#C76542",
primary600: "#A54F31",

secondary100: "#DCDDE9",
secondary200: "#BCC0D6",
secondary300: "#9196B9",
secondary400: "#626894",
secondary500: "#41476E",

accent100: "#FFEED4",
accent200: "#FFE1B2",
accent300: "#FDD495",
accent400: "#FBC878",
accent500: "#FFBB50",

angry100: "#F2D6CD",
angry500: "#C03403",

overlay20: "rgba(25, 16, 21, 0.2)",
overlay50: "rgba(25, 16, 21, 0.5)",
} as const

export const colors = {
/\*\*

- The palette is available to use, but prefer using the name.
- This is only included for rare, one-off cases. Try to use
- semantic names as much as possible.
  \*/
  palette,
  /\*\*
- A helper for making something see-thru.
  \*/
  transparent: "rgba(0, 0, 0, 0)",
  /\*\*
- The default text color in many components.
  \*/
  text: palette.neutral800,
  /\*\*
- Secondary text information.
  \*/
  textDim: palette.neutral600,
  /\*\*
- The default color of the screen background.
  \*/
  background: palette.neutral200,
  /\*\*
- The default border color.
  \*/
  border: palette.neutral400,
  /\*\*
- The main tinting color.
  \*/
  tint: palette.primary500,
  /\*\*
- The inactive tinting color.
  \*/
  tintInactive: palette.neutral300,
  /\*\*
- A subtle color used for lines.
  \*/
  separator: palette.neutral300,
  /\*\*
- Error messages.
  \*/
  error: palette.angry500,
  /\*\*
- Error Background.
  \*/
  errorBackground: palette.angry100,
  } as const

You are an expert in TypeScript, Node.js, Next.js App Router, React, Shadcn UI, Radix UI, 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.

**TypeScript Usage**

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

**Syntax and Formatting**

- Avoid unnecessary curly braces in conditionals; use concise syntax for simple statements.
- Use declarative JSX.

**UI and Styling**

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

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

**Database Querying & Data Model Creation**

- Use Prisma sdk for query database.
- For data model, read the .prisma files.

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

**Follow Next.js docs for Data Fetching, Rendering, and Routing.**

**React component syntax **

Always use this syntax: export const MyComponent = (props: Props) => {}

**PostgresQL**

Always use valid PostgresQL syntax with quotes for table and columns name.

You are an expert in Web Development using the ShipFast boilerplate stack: JavaScript, Node.js, React, Next.js App Router, Tailwind CSS, ShadCDN, NextAuth and PocketBase.

Code Style and Structure

Write concise, technical JavaScript 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.jsx and ButtonSignin.jsx, CardAnalyticsMain.jsx and CardAnalyticsData.jsx, 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 JSX.
UI and Styling

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

Code Style and Structure:
- Follow PEP 8 guidelines for Python code style
- Use meaningful variable and function names (snake_case for variables and functions, PascalCase for classes)
- Keep functions small and focused on a single task
- Use docstrings for modules, classes, and functions
- Organize code into logical modules and packages
- Use virtual environments for project isolation

Python-specific Conventions:
- Prefer list comprehensions and generator expressions over map() and filter()
- Use context managers (with statements) for resource management
- Utilize decorators for cross-cutting concerns (e.g., logging, timing)
- Leverage type hints for improved code readability and tooling support
- Use f-strings for string formatting

Framework and API Development:
- Use FastAPI as the primary framework for building high-performance APIs
  - Leverage FastAPI's automatic OpenAPI (Swagger) documentation
  - Utilize dependency injection for clean, testable code
- Implement RESTful API design principles
- Use Pydantic for data validation, serialization, and settings management
  - Define request and response models using Pydantic
  - Utilize Pydantic's `BaseSettings` for configuration management

Database and Data Modeling:
- Use SQLModel, which combines SQLAlchemy core with Pydantic models
  - Leverage SQLModel's ability to use the same models for database tables and API schemas
  - Utilize SQLModel's async support for high-performance database operations
- Implement database migrations using Alembic
- Use connection pooling for efficient database connections
- Implement proper indexing for frequently queried fields

Authentication and Security:
- Implement JWT for stateless authentication
  - Use FastAPI's built-in security utilities
- Use bcrypt for password hashing
- Apply CORS policies using FastAPI's CORS middleware
- Implement rate limiting for API endpoints (consider using FastAPI's dependencies for this)

Error Handling and Logging:
- Use FastAPI's exception handlers for consistent error responses
- Implement custom exception classes for application-specific errors
- Use a logging framework (e.g., Python's built-in logging module)
- Structure log messages for easy parsing and analysis

Frontend Development:
- For server-side rendering, consider using FastAPI with Jinja2 templates
- Implement responsive design using CSS frameworks (e.g., Bootstrap)
- For single-page applications, use a JavaScript framework (e.g., React, Vue.js) that consumes your FastAPI backend

Testing:
- Write unit tests using pytest
- Implement integration tests for API endpoints using FastAPI's TestClient
- Use factories (e.g., Factory Boy) for test data generation
- Aim for high test coverage, especially for critical paths
- Utilize Pydantic's `parse_obj_as` for easy test data creation

Asynchronous Processing:
- Leverage FastAPI's asynchronous capabilities for concurrent processing
- For background tasks, use FastAPI's background tasks feature or Celery for more complex scenarios
- Implement message queues (e.g., RabbitMQ, Redis) for task management if needed

Deployment and DevOps:
- Use Docker for containerization
  - Create optimized Dockerfiles for your FastAPI applications
- Implement CI/CD pipelines (e.g., GitLab CI, GitHub Actions)
- Use environment variables for configuration management
  - Utilize Pydantic's `BaseSettings` to load and validate environment variables
- Implement health check endpoints for monitoring

Performance Optimization:
- Leverage FastAPI's asynchronous capabilities for I/O-bound operations
- Use caching mechanisms (e.g., Redis) for frequently accessed data
- Implement database query optimization techniques with SQLModel
- Profile code to identify and resolve bottlenecks

API Documentation:
- Utilize FastAPI's automatic interactive API documentation (Swagger UI and ReDoc)
- Keep API documentation up-to-date by maintaining accurate Pydantic models and FastAPI path operation functions

Version Control:
- Use Git for version control
- Implement feature branching and pull request workflows
- Write meaningful commit messages

Dependencies Management
- Use pip and requirements.txt for managing project dependencies
- Consider using Poetry for more advanced dependency management

Remember to keep your code DRY (Don't Repeat Yourself), follow SOLID principles, and prioritize readability and maintainability in your Python full-stack development projects. Leverage the power of FastAPI, SQLModel, and Pydantic to create robust, type-safe, and high-performance applications.