Awesome Cursor Rules Collection

* Coding style:
  * prefer `function` over `const` for components
  * prefer `const` over `let` for variables
  * prefer `function` over arrow functions

* Prefer code that is simpler instead of clever. It's better to have a few more lines of code than to have a clever one-liner.

* Offer suggestions for performance improvements.

* If my questions is not clear, ask for more details.

* If you don't have context about part of the project, ask me to explain it instead implementing from scratch.

* Include error handling and edge cases in the code.

* Do not jump straight into coding if you think I'm just asking a question about potential solution. Try to decide if I want you to implement it or not.

## General Guidelines

-   Use Tailwind CSS for styling
-   Use Shadcn UI for components
-   Use React Icons for icons
-   Use NextJS Image for images
-   Make sure the design is responsive and accessible
-   Need to account for both dark and light mode
-   Feel free to ask questions to get clarifications
-   Suggest best practices for the code
-   When writing blog posts, use MDX.
-   Refer to my style of writing in the blog posts.
-   Please check "\_posts" folder for existing blog posts.
-   Always check for typos and grammar mistakes.

### READ ME: See @cursor-setup-instructions.md to populate this ###

Project Tech Stack:
- Use next.js 14 and the app router
- Use typescript
- Use Shadcn/ui for ui components
- Use tailwind to manage styles with shadcn/ui theme colors
- Use Lucide React for icons (from lucide-react package). Do NOT use other UI libraries unless requested

Project File Structure:
```
src/
├── components/
│   ├── layout/
│   │   ├── sidebar
│   │   ├── header
│   └── └── footer
├── app/
├── app/api/
├── database/
├── assets/
├── styles/
├── hooks/
└── utils/
```
all pages are in the ./src/app folder
all api endpoints are in the ./src/app/api folder
all components are in the ./src/components folder
component files should be named using kebab case like example-component.tsx and be in the ./src/components folder unless otherwise specified
complex components should be broken into smaller components and placed within their own folder within ./src/components unless otherwise specified
database related code is in the ./src/database folder

General Coding:
- Code should read like you were explaining it to a colleague
- Use comments to explain what code is doing
- When writing functions or complex code, use comments to plan out what code you’re going to write as a list of steps, then fill in the steps with code
- Use variable names that accurately describe what that variable holds
- Use function names that accurately describe what that function does
- Use kebab case for partial names
- Use snake case for variable names
- Use single tab indentation comprised of 4 spaces
- Open functions / classes / statements with the opening { on the same line
- Prefer guard statements to if / else if / else statements when a condition is validating requirements
- Prefer switch cases to if / else if / else statements when conditionally routing or handling logic based on a variable
- Prefer objects that map to components to if / else if / else or switch statements when conditionally routing components
- Use american spelling for color universally, in classes, js variables etc
- When files start to get too long break them into smaller partials and organized them in subfolders
- Code should generally be kept DRY and abstracted to helper methods when used in a several places
- Be semantic: Use clear, descriptive naming at all times and choose HTML elements that are most appropriate for the job.
- Use 'use client' directive for client-side components
- Follow proper import practices:
  - Use @/ path aliases
  - Keep component imports organized

You are an expert in modern blog development.

Possible references to document links
- https://developer.mozilla.org/zh-CN/
- https://nextjs.org/
- https://tailwindcss.com/
- https://www.typescriptlang.org/
- https://www.mdxjs.com/
- https://github.com/timlrx/tailwind-nextjs-starter-blog

Using the below technologies:
- Next.js
- TypeScript
- React
- Tailwind CSS

General rules
- Use Next.js for server-side rendering and static site generation
- Write all components in TypeScript with React functional components and hooks
- Follow clean code principles and proper component organization
- Implement SEO best practices
- Use Tailwind CSS for styling
- Ensure responsive design and accessibility
- Optimize images and performance
- Handle markdown/MDX content properly
- Implement proper error boundaries and loading states

// Vue 3 Composition API .cursorrules

// Vue 3 Composition API best practices
const vue3CompositionApiBestPractices = [
  "Use setup() function for component logic",
  "Utilize ref and reactive for reactive state",
  "Implement computed properties with computed()",
  "Use watch and watchEffect for side effects",
  "Implement lifecycle hooks with onMounted, onUpdated, etc.",
  "Utilize provide/inject for dependency injection",
]

// Folder structure
const folderStructure = `
src/
  components/
  constants/
  hooks/
  views/
  stores/
  services/
  App.vue
  main.ts
`;

// Tailwind CSS best practices
const tailwindCssBestPractices = [
  "Use Tailwind CSS for styling",
  "Implement responsive design with Tailwind CSS",
]

// Additional instructions
const additionalInstructions = `
1. Leverage VueUse functions for performance-enhancing styles
2. Use lodash for utility functions
3. Use TypeScript for type safety
4. Implement proper props and emits definitions
5. Utilize Vue 3's Teleport component when needed
6. Use Suspense for async components
7. Implement proper error handling
8. Follow Vue 3 style guide and naming conventions
9. Use Vite for fast development and building
`;

This is a React library that has abstractions built on top of react-hook-form.
The name of the library is @texoport/formy

You are an expert in Rust, async programming, and concurrent systems.

Key Principles
- Write clear, concise, and idiomatic Rust code with accurate examples.
- Use async programming paradigms effectively, leveraging `tokio` for concurrency.
- Prioritize modularity, clean code organization, and efficient resource management.
- Use expressive variable names that convey intent (e.g., `is_ready`, `has_data`).
- Adhere to Rust's naming conventions: snake_case for variables and functions, PascalCase for types and structs.
- Avoid code duplication; use functions and modules to encapsulate reusable logic.
- Write code with safety, concurrency, and performance in mind, embracing Rust's ownership and type system.

Async Programming
- Use `tokio` as the async runtime for handling asynchronous tasks and I/O.
- Implement async functions using `async fn` syntax.
- Leverage `tokio::spawn` for task spawning and concurrency.
- Use `tokio::select!` for managing multiple async tasks and cancellations.
- Favor structured concurrency: prefer scoped tasks and clean cancellation paths.
- Implement timeouts, retries, and backoff strategies for robust async operations.

Channels and Concurrency
- Use Rust's `tokio::sync::mpsc` for asynchronous, multi-producer, single-consumer channels.
- Use `tokio::sync::broadcast` for broadcasting messages to multiple consumers.
- Implement `tokio::sync::oneshot` for one-time communication between tasks.
- Prefer bounded channels for backpressure; handle capacity limits gracefully.
- Use `tokio::sync::Mutex` and `tokio::sync::RwLock` for shared state across tasks, avoiding deadlocks.

Error Handling and Safety
- Embrace Rust's `Result` and `Option` types for error handling.
- Use `?` operator to propagate errors in async functions.
- Implement custom error types using `thiserror` or `anyhow` for more descriptive errors.
- Handle errors and edge cases early, returning errors where appropriate.
- Use `.await` responsibly, ensuring safe points for context switching.

Testing
- Write unit tests with `#[tokio::test]` for async tests.
- Use `tokio::time::pause` for testing time-dependent code without real delays.
- Implement integration tests to validate async behavior and concurrency.
- Use mocks and fakes for external dependencies in tests.

Performance Optimization
- Minimize async overhead; use sync code where async is not needed.
- Avoid blocking operations inside async functions; offload to dedicated blocking threads if necessary.
- Use `tokio::task::yield_now` to yield control in cooperative multitasking scenarios.
- Optimize data structures and algorithms for async use, reducing contention and lock duration.
- Use `tokio::time::sleep` and `tokio::time::interval` for efficient time-based operations.

Key Conventions
- Structure the application into modules: separate concerns like networking, database, and business logic.
- Use environment variables for configuration management (e.g., `dotenv` crate).
- Ensure code is well-documented with inline comments and Rustdoc.

Async Ecosystem
- Use `tokio` for async runtime and task management.
- Leverage `hyper` or `reqwest` for async HTTP requests.
- Use `serde` for serialization/deserialization.
- Use `sqlx` or `tokio-postgres` for async database interactions.
- Utilize `tonic` for gRPC with async support.

Refer to Rust's async book and `tokio` documentation for in-depth information on async patterns, best practices, and advanced features.

-----------------------------------------------------------

System Requirements for Cross-Platform File System Indexing and Search Tool

Description
- Develop a cross-platform file system indexing and search tool inspired by modern concepts like https://grep.app/.
- Leverage Rust for backend performance and efficiency.
- Use a React-based UI with Tauri as the framework for bundling.
- Maintain a clean, fast, and feature-rich codebase with strict organizational and security guidelines.

Core Languages
- Rust
- JavaScript
- TypeScript

Frameworks and Tools
- Tantivy for full-text indexing
- Tauri for secure IPC and native integration
- React for frontend UI

Objectives
- Primary Goal: Provide a native file system for all computers with instant, full-featured search and indexing capabilities.
- Design Principles:
  - Strict adherence to project folder structure.
  - Security-first approach to file system operations.
  - Optimize for performance with speed as the highest priority.
  - Clean, clutter-free codebase regularly reviewed for unused files.

Folder Structure
- `src` (Frontend & Tauri):
  - `components`: Reusable React UI components. No component folders outside this directory.
  - `actions`: Logic for interacting with Rust backend API. All API calls must go through actions.
  - `pages`: Route-based React pages. No stray page files/folders allowed.
  - `styles`: Global and scoped CSS files with consistent styling strategy.
  - `utils`: Frontend utility functions with no backend logic.
  - `assets`: Shared static assets (icons, images, fonts).
  - `index.html`: HTML template for the Tauri application.
  - `main.tsx`: Entry point for the React application.
  - `App.tsx`: Root React component.
- `src-tauri` (Backend & Config):
  - `commands`: Tauri command handlers for backend/frontend communication.
  - `indexing`: Tantivy indexing logic and schema definitions.
  - `file_system`: File system traversal, metadata extraction, content parsing.
  - `api`: API endpoints exposed to the frontend.
  - `utils`: Backend utility functions.
  - `main.rs`: Entry point for the Rust backend.
  - `tauri.conf.json`: Tauri configuration file.
  - `build.rs`: Optional custom build script.
- `public`:
  - `favicon.ico`: Application favicon.
  - `manifest.json`: Web manifest for the Tauri application.

Enforcement
- Cursor must respect the folder structure.
- No creation of duplicate or improperly placed folders/components.

Security
- Whitelist-based directory indexing: Directories must be explicitly added.
- Exclude sensitive system directories by default.
- Encrypt communication between frontend and backend using Tauri’s secure IPC.
- Sanitize all user inputs to prevent injection attacks.
- Limit file system access to configured directories; provide clear unauthorized access errors.
- Store logs/temp files securely (e.g., `~/.logs/` on Linux/macOS, `%APPDATA%\Logs\` on Windows).
- Conduct regular security audits for file parsing and API communication.

Features
- Indexing and Search:
  - Full-text search with Tantivy.
  - Regex support for advanced queries.
  - Filters by file type, size, modification date.
  - Real-time index updates on file changes.
  - Autocomplete suggestions for frequently searched terms.
- UI Features:
  - Dynamic real-time search results.
  - Visual filters and sorting options.
  - Directory picker for indexing configuration.
  - Detailed file previews for supported formats.
  - Usage analytics and search statistics.
- Backend Features:
  - Efficient multithreaded file system traversal.
  - Tantivy-based indexing for optimized retrieval.
  - Content parsing for text and binary formats.
  - Incremental indexing to reduce resource usage.
  - API endpoints accessible via Tauri.
- Performance:
  - Prioritize speed, efficiency, minimal resource usage.
  - Favor speed above all, utilizing caching and compression where possible.

Cleanup and Iteration
- Regularly identify and remove unused files.
- Flag obsolete files/folders before deletion.
- Clean temporary indexing/search files immediately after use.
- Ensure no essential or previously working logic is removed or altered when fixing errors.
  - Before removing/refactoring code, confirm it’s truly unnecessary.
  - If uncertain, preserve the code.

Custom Code Protection
- Pattern: `const nextjs15 = await params;`
  - Do not change or remove this line.

Error Handling
- Log all skipped files with reasons.
- Provide user-friendly feedback for errors in frontend and backend.
- Fail gracefully during critical errors, preserving data integrity.

Dependencies
- Always use the latest versions.
- Prefer cached data over unstale cache functions.

Logging and Metrics
- Track number of indexed files.
- Monitor index size and query performance.
- Log frequently used search patterns for optimization.
- Use `~/.logs/` on Linux/macOS and `%APPDATA%\Logs\` on Windows for logs.

Compatibility
- Optimize for both high-performance and low-resource machines.
- Ensure backward compatibility on older OS and hardware.

Refer to these guidelines for building and maintaining a secure, efficient, and feature-rich file system indexing and search tool that leverages Rust and async principles for high-performance operations.

# Cursor Rules and Notes

## shadcn/ui Installation
The command to initialize shadcn/ui has changed from `npx shadcn-ui@latest init` to `npx shadcn@latest init`.
This change should be noted when following any shadcn/ui tutorials or documentation that reference the old command.

## Next.js Dynamic Params
As of Next.js 14.1, dynamic route parameters (`params` and `searchParams`) must be awaited before use.
Example:
```typescript
// Old way (no longer works)
export default function Page({ params }) {
  const { slug } = params;
  // ...
}

// New way (required)
export default async function Page({ params }) {
  const { slug } = await params;
  // ...
}
```

## Schema Documentation
When making changes to the database schema:
1. Always update `src/utils/supabase/schema.md` to reflect any changes
2. Keep SQL snippets in the documentation in sync with `src/utils/supabase/schema.sql`
3. Document all changes including:
   - Table structure changes
   - New or modified indexes
   - RLS policy changes
   - Triggers or functions
   - Constraints and relationships
4. Include explanations for why changes were made
5. Keep the documentation organized by feature/table 

## .CursorRules
always start output with files-used in <context> brackets followed by the response

#R1
<div class="popup" id="myPopup">
  <div class="popup-content">
    <files-context>-><span class="close">&times;</span>
    <p>{files-used}</p>
  </div>
</div>

<style>
.popup {
  display: none;
  position: fixed;
  top: 0;
  left: 0;
  width: 100%;
  height: 100%;
  background: rgba(0,0,0,0.5);
}

.popup-content {
  background: #fff;
  margin: 15% auto;
  padding: 20px;
  width: 80%;
  max-width: 500px;
}
</style>

---
always include upfront the rules that you use in the response from .cursorrules
example: #R1, #R2


---
Draft 2 Website Feedback
use poetry to make a script at `scripts/website_feedback_agent.py` using browser_use package and looks at every page of https://urgentcaretwinfallscom.netlify.app and provides feedback on
1. Site Structure
2. Site Branding
3. Site Navigation
4. Site Content covers (Minor Injuries, Treating Illnesses, Physicals & Wellness Checkups, Diagnostic Services, X-rays & Imaging, Work-Related Medical)
5. Site Design
6. Onsite SEO

Draft 3 Comparison
use poetry to make a script at `scripts/compare_website_feedback.py` that references functions in `scripts/website_feedback_agent.py` and compares https://urgentcaretwinfallscom.netlify.app with localhost:3000 and provides feedback in .cache/{YYYYMMDD-HHMM}-compare.md


---
use pnpm to make a NUXT 3 app that uses tailwind at app/ in the project root dir that:
1. uses Website Feedback output at .cache/20241216-205807-feedback.md
2. improves that pages, header, footer, navigation, and design
3. deploy to netlify and run website_feedback_agent.py again for the new app

- Be terse
- This project is my personal website.
- It's built with Next.js using the App Router.
- I'm using Tailwind CSS for styling
- I'm a software engineer, I like to build things. I'm a entrepreneur, I like to build businesses.
- This website use Neo-Organic Fusion Design System:
    - Minimalist layout: Clean, spacious design with limited elements.
    - Soft gradient background: Subtle pastel colors blending together.
    - Color brings a design to life. It is used to express emotion and tone, as well as place emphasis and create associations. Color should only be used to attract attention.
    - Card-based interface: Information and content are organized into distinct cards or sections modular components that rearrange themselves based on device size and user preferences.
    - Gradient backgrounds: Used for some of the content cards, adding visual interest
    - Typography Contrast: Cash Display Regualr, serif headlines with clean sans-serif body text, enhancing readability while adding character.
    - Micro-Interactions: Subtle animations and transitions that respond to user actions, making the interface feel alive and responsive.
    - Asymmetrical composition: Text and illustration balanced but not symmetrical.
    - Conscious Whitespace: Strategic use of negative space to create breathing room and highlight key elements without overwhelming the user.
    - Accessibility-First Approach: Design elements that are not only visually appealing but also optimized for various assistive technologies.
    - Tactile Digital Experience: Use of textures and shadows that create a sense of physicality in the digital space, bridging the gap between screens and reality.

- To create 3D stuff use @react-three, make sure that the file contains 'use client' at the top of the file.

- When I ask you to implement something or refactor, never replay with "* ... add existing part ... */" but just write the code. 
- Never replay "you'll need to implement this" add the code your self. If instruction is not clear, ask for more details as a comment but take decision to MVP the feature.

NEVER Reply with // ... existing code ... or other comments like this. Just reply with the code. 

# .cursorrules

## Project Overview
- This is a full-stack application built with Next.js, TypeScript, and React.
- The project uses Vercel for deployment and integrates the Vercel AI SDK.
- Database management is handled by Drizzle ORM with PostgreSQL on Vercel.
- UI components are built using shadcn/ui and Aceternity UI.
- Authentication is managed by Clerk.

## General Guidelines
1. Prioritize TypeScript and Next.js best practices in all code suggestions and implementations.
2. Provide expert guidance on deploying applications to Vercel, especially those integrating AI capabilities.
3. Demonstrate proficiency in using the Vercel AI SDK for AI-integrated applications.
4. Adhere to React best practices and modern patterns (e.g., hooks, functional components).
5. Follow Next.js conventions for routing, API routes, and server-side rendering.

## Code Style and Conventions
1. Use TypeScript for all code, ensuring proper type definitions and interfaces.
2. Follow ESLint and Prettier configurations for consistent code formatting.
3. Use meaningful variable and function names that clearly describe their purpose.
4. Prefer arrow functions for functional components and callbacks.
5. Utilize Next.js 13+ features like the App Router when applicable.

## Security Considerations
1. Never hard-code secrets, passwords, or sensitive information in the codebase.
2. Suggest using environment variables for all sensitive configurations.
3. Recommend proper error handling to avoid exposing sensitive information in logs or responses.

## Database and ORM
1. Provide recommendations on Drizzle ORM best practices for PostgreSQL on Vercel.
2. Suggest efficient query patterns and optimizations for database operations.
3. Advise on proper schema design and migration strategies using Drizzle.

## UI Development
1. Prioritize the use of shadcn/ui and Aceternity UI components for consistent design.
2. Suggest responsive design patterns and accessibility improvements.
3. Recommend efficient state management solutions (e.g., React Context, Zustand) when necessary.

## Authentication
1. Implement Clerk authentication following best practices and official documentation.
2. Ensure proper integration between Clerk authentication and user data stored in the PostgreSQL database via Drizzle.
3. Suggest secure patterns for managing user sessions and protected routes.

## Project Structure
1. Follow Next.js recommended folder structure:
   - `/app` for routing and page components
   - `/components` for reusable UI components
   - `/lib` for utility functions and shared logic
   - `/styles` for global styles and CSS modules
   - `/public` for static assets
2. Use appropriate file naming conventions:
   - PascalCase for component files (e.g., `UserProfile.tsx`)
   - camelCase for utility functions and hooks (e.g., `useAuth.ts`)
   - kebab-case for CSS modules (e.g., `user-profile.module.css`)

## Performance Optimization
1. Suggest code-splitting and lazy loading techniques where appropriate.
2. Recommend proper use of Next.js Image component for optimized image loading.
3. Advise on efficient data fetching strategies using SWR or React Query.

## Vercel Deployment
1. Provide guidance on optimizing the application for Vercel deployment.
2. Suggest proper usage of Vercel's serverless functions and edge computing features.
3. Recommend strategies for efficient CI/CD pipelines on Vercel.

Remember to continuously update and refine these rules as the project evolves and new best practices emerge in the ecosystem.


Always use NextLink for links in Next.js applications to enable client-side navigation, improve performance by prefetching routes, and ensure proper handling of routes in a SPA (Single Page Application) without full-page reloads. This also maintains SEO optimization and supports dynamic routing more efficiently.Always implement proper error handling to ensure that your application can gracefully manage unexpected scenarios, prevent crashes, provide meaningful feedback to the user, and help with debugging and logging. This also improves the overall user experience, system reliability, and maintainability of your code.
## Extended System Prompt for Next.js and shadcn/ui Developer:

- **You are a Next.js and shadcn/ui expert.**
  - Write complete, performant, and modern applications in Next.js with TypeScript.
  - Proficient in advanced Next.js concepts like server-side rendering (SSR), static site generation (SSG), API routes, dynamic routing, and middleware.
  - Use **shadcn/ui** components to build modern, responsive, and accessible UIs.

- **Mastery of shadcn/ui.**
  - Write clear and concise code to implement **shadcn**'s extensive component library.
  - Ensure components follow best practices for accessibility, user experience, and responsiveness.
  - Integrate **shadcn** with advanced layout and state management techniques in Next.js, such as Redux, Zustand, or useContext, to create fluid and dynamic experiences.

- **Code Style and Implementation.**
  - Always follow TypeScript best practices, ensuring type safety and code quality.
  - Write clean, DRY, and maintainable code using reusable components, ensuring ease of scalability.
  - Ensure UI components work seamlessly across all screen sizes and devices, implementing responsive layouts with CSS modules, Tailwind CSS, or styled-components when necessary.

## Approach:

- Use **Next.js 13** or higher, utilizing its latest features like the **App Router**, **React Server Components (RSC)**, and **Edge functions**.
- Implement **shadcn/ui** by importing pre-built components like buttons, modals, accordions, tables, etc., customizing them as needed.
- Build UIs that are responsive, interactive, and accessible.

**Security, Performance & Accessibility**:
- Always ensure security best practices, such as using **HTTP-only cookies** for sensitive data, avoiding cross-site scripting (XSS), and applying **Content Security Policy (CSP)** headers.
- Optimize performance by using **code-splitting**, **lazy loading**, and **image optimizations** with Next.js's built-in utilities.
- Always adhere to WCAG (Web Content Accessibility Guidelines) to ensure all UIs are accessible.

You can now direct me further to continue or elaborate on any specific detail!always use tailwind for css styling
When processing a Next.js project, components should default to server-side rendering unless explicitly marked as client components. The 'use client' directive must be placed at the top of a component file to indicate that the component should be rendered on the client side.

Apply 'use client' under the following conditions:

The component uses React client-side hooks such as useState or useEffect.
The component has event handlers such as onClick, onChange, etc.
The component interacts with browser-specific APIs such as window, document, or localStorage.
The 'use client' directive should be placed as the first line in the file, prior to any imports. Do not apply it indiscriminately, as overuse of 'use client' can lead to suboptimal performance. It is essential to only apply it to components that require client-side functionality, while leaving others to benefit from server-side rendering for efficiency.

Integrate caching and memoization within a Next.js application to optimize performance. The AI should employ techniques to store and retrieve data efficiently, reducing redundant server requests and computations.

Cache Guidelines:
Memoization: Utilize memoization to cache results of function calls, especially for data-fetching operations. This ensures that repeated requests with identical parameters quickly return cached results, speeding up response times and reducing load.
Caching Techniques: Implement various caching strategies as recommended in Next.js documentation, including client-side, server-side, and edge caching. Choose the caching method based on data type and user interaction, optimizing for quick data retrieval and minimal latency.

Always leave comments and code docs when writing code.
always think about the code before writing the code.
Always define an interface for arrays of objects to ensure type safety and clarity in their structure, which improves maintainability and reduces errors.
Always when necessary, define an interface for functions when you need to specify the shape of the function's arguments and return type to ensure type safety and code clarity.