@qazuor/claude-code-config 0.1.0

package/templates/skills/state/tanstack-query-patterns.md

@@ -0,0 +1,299 @@
+---
+name: tanstack-query-patterns
+category: state
+description: TanStack Query (React Query) server state management patterns
+usage: Use when managing server state with automatic caching, refetching, and optimistic updates
+input: API endpoints, query keys, mutation operations
+output: Query hooks, mutation hooks, cache management
+config_required:
+  stale_time: "Time until data is considered stale"
+  cache_time: "Time until inactive data is garbage collected"
+  retry_config: "Retry strategy for failed requests"
+  refetch_on_window_focus: "Whether to refetch on window focus"
+  api_base_url: "Base URL for API requests"
+---
+
+# TanStack Query Patterns
+
+## ⚙️ Configuration
+
+| Setting | Description | Example |
+|---------|-------------|---------|
+| `stale_time` | Time until data is stale | `5 * 60 * 1000` (5 minutes) |
+| `cache_time` | Time until inactive data GC | `30 * 60 * 1000` (30 minutes) |
+| `retry_config` | Failed request retry strategy | `3`, exponential backoff |
+| `refetch_on_window_focus` | Refetch when window regains focus | `true`, `false` |
+| `api_base_url` | API base URL | `/api`, `https://api.example.com` |
+
+## Purpose
+
+Manage server state with:
+- Automatic caching and background refetching
+- Stale-while-revalidate pattern
+- Optimistic updates
+- Infinite queries and pagination
+- Minimal boilerplate
+
+## Setup
+
+```typescript
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { ReactQueryDevtools } from '@tanstack/react-query-devtools';
+
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      staleTime: 1000 * 60 * 5, // 5 minutes
+      gcTime: 1000 * 60 * 30, // 30 minutes
+      retry: 3,
+      retryDelay: (attemptIndex) => Math.min(1000 * 2 ** attemptIndex, 30000),
+      refetchOnWindowFocus: true,
+    },
+    mutations: {
+      retry: 1,
+    },
+  },
+});
+
+function App() {
+  return (
+    <QueryClientProvider client={queryClient}>
+      <Router />
+      <ReactQueryDevtools initialIsOpen={false} />
+    </QueryClientProvider>
+  );
+}
+```
+
+## Query Patterns
+
+### Basic Query
+
+```typescript
+import { useQuery } from '@tanstack/react-query';
+
+async function fetchUser(userId: string): Promise<User> {
+  const response = await fetch(`/api/users/${userId}`);
+  if (!response.ok) throw new Error('Failed to fetch user');
+  return response.json();
+}
+
+function useUser(userId: string) {
+  return useQuery({
+    queryKey: ['user', userId],
+    queryFn: () => fetchUser(userId),
+    enabled: !!userId,
+  });
+}
+
+// Usage
+function UserProfile({ userId }: { userId: string }) {
+  const { data: user, isLoading, error, refetch } = useUser(userId);
+
+  if (isLoading) return <Spinner />;
+  if (error) return <Error message={error.message} />;
+
+  return <div>{user?.name}</div>;
+}
+```
+
+### Infinite Query
+
+```typescript
+import { useInfiniteQuery } from '@tanstack/react-query';
+
+interface PostsPage {
+  posts: Post[];
+  nextCursor: string | null;
+}
+
+function useInfinitePosts() {
+  return useInfiniteQuery({
+    queryKey: ['posts'],
+    queryFn: ({ pageParam }) => fetchPosts(pageParam),
+    initialPageParam: undefined as string | undefined,
+    getNextPageParam: (lastPage) => lastPage.nextCursor ?? undefined,
+  });
+}
+
+// Usage
+function PostList() {
+  const { data, fetchNextPage, hasNextPage, isFetchingNextPage } = useInfinitePosts();
+
+  return (
+    <div>
+      {data?.pages.map((page, i) => (
+        <Fragment key={i}>
+          {page.posts.map((post) => <PostCard key={post.id} post={post} />)}
+        </Fragment>
+      ))}
+      {hasNextPage && (
+        <button onClick={() => fetchNextPage()} disabled={isFetchingNextPage}>
+          {isFetchingNextPage ? 'Loading...' : 'Load More'}
+        </button>
+      )}
+    </div>
+  );
+}
+```
+
+## Mutation Patterns
+
+### Basic Mutation
+
+```typescript
+import { useMutation, useQueryClient } from '@tanstack/react-query';
+
+function useCreatePost() {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: createPost,
+    onSuccess: (newPost) => {
+      // Invalidate and refetch
+      queryClient.invalidateQueries({ queryKey: ['posts'] });
+
+      // Or update cache directly
+      queryClient.setQueryData(['post', newPost.id], newPost);
+    },
+    onError: (error) => {
+      toast.error(error.message);
+    },
+  });
+}
+
+// Usage
+function CreatePostForm() {
+  const createPost = useCreatePost();
+
+  const handleSubmit = async (data: CreatePostInput) => {
+    try {
+      await createPost.mutateAsync(data);
+      toast.success('Post created!');
+    } catch (error) {
+      // Error handled in mutation
+    }
+  };
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <button type="submit" disabled={createPost.isPending}>
+        {createPost.isPending ? 'Creating...' : 'Create Post'}
+      </button>
+    </form>
+  );
+}
+```
+
+### Optimistic Updates
+
+```typescript
+function useUpdatePost() {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: ({ id, data }: { id: string; data: Partial<Post> }) =>
+      updatePost(id, data),
+
+    onMutate: async ({ id, data }) => {
+      // Cancel outgoing refetches
+      await queryClient.cancelQueries({ queryKey: ['post', id] });
+
+      // Snapshot previous value
+      const previousPost = queryClient.getQueryData<Post>(['post', id]);
+
+      // Optimistically update
+      if (previousPost) {
+        queryClient.setQueryData<Post>(['post', id], {
+          ...previousPost,
+          ...data,
+        });
+      }
+
+      return { previousPost };
+    },
+
+    onError: (err, variables, context) => {
+      // Rollback on error
+      if (context?.previousPost) {
+        queryClient.setQueryData(['post', variables.id], context.previousPost);
+      }
+    },
+
+    onSettled: (data, error, variables) => {
+      // Always refetch after error or success
+      queryClient.invalidateQueries({ queryKey: ['post', variables.id] });
+    },
+  });
+}
+```
+
+## Query Key Patterns
+
+```typescript
+export const queryKeys = {
+  all: ['posts'] as const,
+  lists: () => [...queryKeys.all, 'list'] as const,
+  list: (filters: PostFilters) => [...queryKeys.lists(), filters] as const,
+  details: () => [...queryKeys.all, 'detail'] as const,
+  detail: (id: string) => [...queryKeys.details(), id] as const,
+};
+
+// Usage
+useQuery({
+  queryKey: queryKeys.detail(postId),
+  queryFn: () => fetchPost(postId),
+});
+
+// Invalidate all posts
+queryClient.invalidateQueries({ queryKey: queryKeys.all });
+```
+
+## Prefetching
+
+```typescript
+// Prefetch on hover
+function PostLink({ postId }: { postId: string }) {
+  const queryClient = useQueryClient();
+
+  const prefetch = () => {
+    queryClient.prefetchQuery({
+      queryKey: ['post', postId],
+      queryFn: () => fetchPost(postId),
+      staleTime: 1000 * 60,
+    });
+  };
+
+  return (
+    <Link to={`/posts/${postId}`} onMouseEnter={prefetch}>
+      View Post
+    </Link>
+  );
+}
+```
+
+## Best Practices
+
+| Practice | Description |
+|----------|-------------|
+| **Structured Query Keys** | Use consistent, hierarchical query keys |
+| **Appropriate Stale Times** | Set stale times per query type based on data volatility |
+| **Enabled Option** | Control query execution with `enabled` |
+| **Error Handling** | Handle errors at both query and component level |
+| **Optimistic Updates** | Improve UX with optimistic updates on mutations |
+| **Prefetching** | Prefetch data on hover or route transitions |
+| **DevTools** | Use React Query DevTools for debugging |
+
+## When to Use
+
+- Any application with server data
+- REST or GraphQL APIs
+- Real-time data with polling
+- Complex caching requirements
+- Background data synchronization
+
+## Related Skills
+
+- `redux-toolkit-patterns` - For client state
+- `zustand-patterns` - For client state
+- `api-app-testing` - Test queries and mutations

package/templates/skills/state/zustand-patterns.md

@@ -0,0 +1,301 @@
+---
+name: zustand-patterns
+category: state
+description: Zustand lightweight state management patterns for React applications
+usage: Use when implementing simple global client state without Redux boilerplate
+input: State structure, actions, persistence needs
+output: Store definitions, hooks, middleware configuration
+config_required:
+  state_organization: "How state is organized (single store vs slices)"
+  persistence: "What state needs to be persisted"
+  storage_type: "Storage mechanism for persistence"
+  devtools: "Whether to enable Redux DevTools integration"
+---
+
+# Zustand Patterns
+
+## ⚙️ Configuration
+
+| Setting | Description | Example |
+|---------|-------------|---------|
+| `state_organization` | State organization strategy | Single store, multiple stores, slices |
+| `persistence` | State to persist | User preferences, auth tokens, cart |
+| `storage_type` | Storage mechanism | localStorage, sessionStorage, AsyncStorage |
+| `devtools` | Redux DevTools integration | `true`, `false` |
+
+## Purpose
+
+Implement lightweight state management with:
+- Minimal boilerplate
+- TypeScript-first design
+- Works outside React components
+- Middleware support (persist, immer, devtools)
+- No providers needed
+
+## Basic Store
+
+```typescript
+import { create } from 'zustand';
+
+interface CounterState {
+  count: number;
+  increment: () => void;
+  decrement: () => void;
+  reset: () => void;
+}
+
+export const useCounterStore = create<CounterState>((set) => ({
+  count: 0,
+  increment: () => set((state) => ({ count: state.count + 1 })),
+  decrement: () => set((state) => ({ count: state.count - 1 })),
+  reset: () => set({ count: 0 }),
+}));
+```
+
+## Async Actions
+
+```typescript
+interface UserState {
+  user: User | null;
+  isLoading: boolean;
+  error: string | null;
+  fetchUser: (id: string) => Promise<void>;
+  updateUser: (data: Partial<User>) => Promise<void>;
+  clearUser: () => void;
+}
+
+export const useUserStore = create<UserState>((set, get) => ({
+  user: null,
+  isLoading: false,
+  error: null,
+
+  fetchUser: async (id: string) => {
+    set({ isLoading: true, error: null });
+    try {
+      const response = await fetch(`/api/users/${id}`);
+      if (!response.ok) throw new Error('Failed to fetch');
+      const user = await response.json();
+      set({ user, isLoading: false });
+    } catch (error) {
+      set({ error: (error as Error).message, isLoading: false });
+    }
+  },
+
+  updateUser: async (data: Partial<User>) => {
+    const currentUser = get().user;
+    if (!currentUser) return;
+
+    set({ isLoading: true, error: null });
+    try {
+      const response = await fetch(`/api/users/${currentUser.id}`, {
+        method: 'PATCH',
+        body: JSON.stringify(data),
+      });
+      const updatedUser = await response.json();
+      set({ user: updatedUser, isLoading: false });
+    } catch (error) {
+      set({ error: (error as Error).message, isLoading: false });
+    }
+  },
+
+  clearUser: () => set({ user: null, error: null }),
+}));
+```
+
+## Slices Pattern
+
+```typescript
+import { create, StateCreator } from 'zustand';
+
+// Auth slice
+interface AuthSlice {
+  token: string | null;
+  isAuthenticated: boolean;
+  login: (token: string) => void;
+  logout: () => void;
+}
+
+const createAuthSlice: StateCreator<AppStore, [], [], AuthSlice> = (set) => ({
+  token: null,
+  isAuthenticated: false,
+  login: (token) => set({ token, isAuthenticated: true }),
+  logout: () => set({ token: null, isAuthenticated: false }),
+});
+
+// User slice
+interface UserSlice {
+  user: User | null;
+  setUser: (user: User | null) => void;
+}
+
+const createUserSlice: StateCreator<AppStore, [], [], UserSlice> = (set) => ({
+  user: null,
+  setUser: (user) => set({ user }),
+});
+
+// Combined store
+type AppStore = AuthSlice & UserSlice;
+
+export const useAppStore = create<AppStore>()((...args) => ({
+  ...createAuthSlice(...args),
+  ...createUserSlice(...args),
+}));
+```
+
+## Middleware
+
+### Persist
+
+```typescript
+import { create } from 'zustand';
+import { persist, createJSONStorage } from 'zustand/middleware';
+
+interface SettingsState {
+  theme: 'light' | 'dark';
+  language: string;
+  notifications: boolean;
+  setTheme: (theme: 'light' | 'dark') => void;
+  setLanguage: (lang: string) => void;
+  toggleNotifications: () => void;
+}
+
+export const useSettingsStore = create<SettingsState>()(
+  persist(
+    (set) => ({
+      theme: 'light',
+      language: 'en',
+      notifications: true,
+      setTheme: (theme) => set({ theme }),
+      setLanguage: (language) => set({ language }),
+      toggleNotifications: () => set((state) => ({ notifications: !state.notifications })),
+    }),
+    {
+      name: 'settings-storage',
+      storage: createJSONStorage(() => localStorage),
+      partialize: (state) => ({
+        theme: state.theme,
+        language: state.language,
+        notifications: state.notifications,
+      }),
+    }
+  )
+);
+```
+
+### Immer
+
+```typescript
+import { create } from 'zustand';
+import { immer } from 'zustand/middleware/immer';
+
+interface TodoState {
+  todos: Todo[];
+  addTodo: (text: string) => void;
+  toggleTodo: (id: string) => void;
+  removeTodo: (id: string) => void;
+}
+
+export const useTodoStore = create<TodoState>()(
+  immer((set) => ({
+    todos: [],
+    addTodo: (text) =>
+      set((state) => {
+        state.todos.push({
+          id: crypto.randomUUID(),
+          text,
+          completed: false,
+        });
+      }),
+    toggleTodo: (id) =>
+      set((state) => {
+        const todo = state.todos.find((t) => t.id === id);
+        if (todo) todo.completed = !todo.completed;
+      }),
+    removeTodo: (id) =>
+      set((state) => {
+        state.todos = state.todos.filter((t) => t.id !== id);
+      }),
+  }))
+);
+```
+
+## Usage Patterns
+
+### Selecting State
+
+```typescript
+// Select single value (re-renders only when count changes)
+const count = useCounterStore((state) => state.count);
+
+// Select action (stable reference)
+const increment = useCounterStore((state) => state.increment);
+
+// Select multiple with shallow comparison
+import { useShallow } from 'zustand/react/shallow';
+
+const { user, isLoading } = useUserStore(
+  useShallow((state) => ({ user: state.user, isLoading: state.isLoading }))
+);
+```
+
+### Outside React
+
+```typescript
+// Get current state
+const currentCount = useCounterStore.getState().count;
+
+// Call actions
+useCounterStore.getState().increment();
+
+// Subscribe to changes
+const unsubscribe = useCounterStore.subscribe((state) => {
+  console.log('Count changed:', state.count);
+});
+```
+
+### Computed Values
+
+```typescript
+interface CartState {
+  items: CartItem[];
+}
+
+export const useCartStore = create<CartState>(() => ({
+  items: [],
+}));
+
+// Use selectors for computed values
+export const useCartTotal = () =>
+  useCartStore((state) =>
+    state.items.reduce((sum, item) => sum + item.price * item.quantity, 0)
+  );
+
+export const useCartItemCount = () =>
+  useCartStore((state) =>
+    state.items.reduce((sum, item) => sum + item.quantity, 0)
+  );
+```
+
+## Best Practices
+
+| Practice | Description |
+|----------|-------------|
+| **Use Selectors** | Always use selectors to minimize re-renders |
+| **Actions in Store** | Keep actions in the store, not components |
+| **TypeScript** | Use TypeScript interfaces for full type safety |
+| **Slices for Large Stores** | Split large stores into slices |
+| **Persist User Preferences** | Use persist middleware for settings |
+| **Immer for Nested Updates** | Use immer for complex nested state |
+
+## When to Use
+
+- Small to medium React applications
+- When Redux is overkill
+- Need state outside React components
+- Simple global state needs
+- With TanStack Query for server state
+
+## Related Skills
+
+- `redux-toolkit-patterns` - For complex state needs
+- `tanstack-query-patterns` - For server state