Qwik Cursor Rules: Resumability and Lazy Loading Guide

---
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
- Leverage Qwik's resumability model instead of traditional hydration
- Use server and client boundaries with the $ suffix
- Implement efficient lazy loading with component$, useTask$, and useVisibleTask$
- Optimize for progressive enhancement and partial hydration
- 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);

  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>
      )}
    />
  );
});