Qwik Cursor Rules

---
description: Enforces best practices for Qwik development, focusing on resumability, component architecture, and optimization patterns. Provides comprehensive guidelines for writing clean, efficient, and maintainable Qwik applications.
globs: ["**/*.tsx", "**/*.jsx", "**/*.ts", "**/*.js"]
---

# Qwik Best Practices

You are an expert in Qwik development and related technologies.
You understand Qwik's unique architecture focused on resumability, lazy loading, and fine-grained reactivity.

### Resumability-Aware Development
- Understand and leverage Qwik's resumability model instead of hydration
- Properly use server and client boundaries with $ suffix
- Implement efficient lazy loading with component$, useTask$, and useVisibleTask$
- Optimize for progressive enhancement and partial hydration
- Properly handle serialization boundaries between server and client

### Component Architecture
- Follow Qwik component patterns with component$ for optimal code-splitting
- Implement proper signal management with useSignal and useStore
- Use resource loaders (routeLoader$, useResource$) for data fetching
- Implement proper route handling with QwikCity
- Use proper event handling with $ suffix for optimal bundling

### Optimization Patterns
- Implement proper lazy loading strategies
- Use fine-grained reactivity for optimal performance
- Implement proper server/client boundary management
- Optimize bundle size with proper code splitting
- Use proper prefetching strategies

### State Management
- Use useSignal for simple reactive state
- Implement useStore for complex state objects
- Use createContextId and useContextProvider for global state
- Implement proper state serialization for resumability
- Use proper state initialization patterns

### Routing and Data Fetching
- Use QwikCity for routing and layouts
- Implement routeLoader$ for server-side data fetching
- Use useResource$ for client-side data fetching
- Implement proper error handling and loading states
- Use proper route parameters and navigation

### Testing and Quality
- Write unit tests with proper component mocking
- Implement E2E tests with Playwright
- Use proper test utilities for Qwik components
- Implement proper error boundaries
- Maintain high test coverage for core business logic

### Examples

```tsx
// Proper component definition with resumability
export const Counter = component$(() => {
  const count = useSignal(0);
  
  // Proper task usage with $ suffix
  useTask$(({ track }) => {
    track(() => count.value);
    console.log('Count changed:', count.value);
  });

  return (
    <div>
      <span>Count: {count.value}</span>
      <button onClick$={() => count.value++}>Increment</button>
    </div>
  );
});

// Proper data fetching with resource loaders
export const useProductData = routeLoader$(async () => {
  const products = await fetchProducts();
  return {
    products,
    categories: await fetchCategories()
  };
});

// Proper client-side resource usage
export const ProductList = component$(() => {
  const products = useResource$(async () => {
    const response = await fetch('/api/products');
    return response.json();
  });

  return (
    <Resource
      value={products}
      onPending={() => <div>Loading...</div>}
      onRejected={(error) => <div>Error: {error.message}</div>}
      onResolved={(data) => (
        <ul>
          {data.map(product => (
            <li key={product.id}>{product.name}</li>
          ))}
        </ul>
      )}
    />
  );
});

## Qwik-Specific Rules

Cursor rules in Qwik enhance your development experience by providing smart navigation and manipulation features tailored for Qwik's unique architecture and features.

### Code Navigation

- Navigate between component definitions and their usages
- Quick access to component props and signals
- Smart navigation through lazy-loaded boundaries
- Jump between server and client components

### Smart Selection

- Select complete component blocks including JSX
- Expand selection to include signal declarations
- Smart selection of resource loaders
- Select complete route handlers

### Code Manipulation

- Quick component optimization helpers
- Automated signal and store management
- Smart import handling for lazy loading
- Route parameter manipulation

## Best Practices

- Use resumability-aware navigation for better code organization
- Leverage Qwik's fine-grained reactivity features
- Utilize progressive enhancement patterns effectively

## Examples

```tsx
// Navigate through component definitions
export const Counter = component$(() => {
  const count = useSignal(0);

  return (
    <div>
      <span>{count.value}</span>
      <button onClick$={() => count.value++}>Increment</button>
    </div>
  );
});

// Smart selection of resource loaders
export const useProductData = routeLoader$(() => {
  return {
    products: getProducts(),
    categories: getCategories()
  };
});

// Component optimization patterns
export const ProductList = component$(() => {
  const products = useResource$(() =>
    fetch('/api/products').then(res => res.json())
  );

  return (
    <Resource
      value={products}
      onPending={() => <div>Loading...</div>}
      onResolved={(data) => (
        <ul>
          {data.map(product => (
            <li key={product.id}>{product.name}</li>
          ))}
        </ul>
      )}
    />
  );
});

{
  "qwik.cursorRules": {
    "componentNavigation": true,
    "smartSelection": true,
    "optimizationHelpers": true,
    "resumabilityAware": true
  }
}