@punks/cli 0.1.16 → 1.0.0

package/dist/skills/frameworks/tanstack-query/tanstack-query/templates/error-boundary.tsx

@@ -0,0 +1,243 @@
+// src/components/ErrorBoundary.tsx
+import { Component, type ReactNode } from 'react'
+import { QueryErrorResetBoundary } from '@tanstack/react-query'
+
+/**
+ * Props and State types
+ */
+type ErrorBoundaryProps = {
+  children: ReactNode
+  fallback?: (error: Error, reset: () => void) => ReactNode
+}
+
+type ErrorBoundaryState = {
+  hasError: boolean
+  error: Error | null
+}
+
+/**
+ * React Error Boundary Class Component
+ *
+ * Required because error boundaries must be class components
+ */
+class ErrorBoundaryClass extends Component<
+  ErrorBoundaryProps & { onReset?: () => void },
+  ErrorBoundaryState
+> {
+  constructor(props: ErrorBoundaryProps & { onReset?: () => void }) {
+    super(props)
+    this.state = { hasError: false, error: null }
+  }
+
+  static getDerivedStateFromError(error: Error): ErrorBoundaryState {
+    return { hasError: true, error }
+  }
+
+  componentDidCatch(error: Error, errorInfo: React.ErrorInfo) {
+    // Log error to error reporting service
+    console.error('Error caught by boundary:', error, errorInfo)
+
+    // Example: Send to Sentry, LogRocket, etc.
+    // Sentry.captureException(error, { contexts: { react: errorInfo } })
+  }
+
+  handleReset = () => {
+    // Call TanStack Query reset if provided
+    this.props.onReset?.()
+
+    // Reset error boundary state
+    this.setState({ hasError: false, error: null })
+  }
+
+  render() {
+    if (this.state.hasError && this.state.error) {
+      // Use custom fallback if provided
+      if (this.props.fallback) {
+        return this.props.fallback(this.state.error, this.handleReset)
+      }
+
+      // Default error UI
+      return (
+        <div
+          style={{
+            padding: '2rem',
+            border: '2px solid #ef4444',
+            borderRadius: '8px',
+            backgroundColor: '#fee',
+          }}
+        >
+          <h2>Something went wrong</h2>
+          <details style={{ whiteSpace: 'pre-wrap', marginTop: '1rem' }}>
+            <summary>Error details</summary>
+            {this.state.error.message}
+            {this.state.error.stack && (
+              <pre style={{ marginTop: '1rem', fontSize: '0.875rem' }}>
+                {this.state.error.stack}
+              </pre>
+            )}
+          </details>
+          <button
+            onClick={this.handleReset}
+            style={{
+              marginTop: '1rem',
+              padding: '0.5rem 1rem',
+              backgroundColor: '#3b82f6',
+              color: 'white',
+              border: 'none',
+              borderRadius: '4px',
+              cursor: 'pointer',
+            }}
+          >
+            Try again
+          </button>
+        </div>
+      )
+    }
+
+    return this.props.children
+  }
+}
+
+/**
+ * Error Boundary with TanStack Query Reset
+ *
+ * Wraps components and catches errors thrown by queries
+ * with throwOnError: true
+ */
+export function ErrorBoundary({ children, fallback }: ErrorBoundaryProps) {
+  return (
+    <QueryErrorResetBoundary>
+      {({ reset }) => (
+        <ErrorBoundaryClass onReset={reset} fallback={fallback}>
+          {children}
+        </ErrorBoundaryClass>
+      )}
+    </QueryErrorResetBoundary>
+  )
+}
+
+/**
+ * Usage Examples
+ */
+
+// Example 1: Wrap entire app
+export function AppWithErrorBoundary() {
+  return (
+    <ErrorBoundary>
+      <App />
+    </ErrorBoundary>
+  )
+}
+
+// Example 2: Wrap specific features
+export function UserProfileWithErrorBoundary() {
+  return (
+    <ErrorBoundary>
+      <UserProfile />
+    </ErrorBoundary>
+  )
+}
+
+// Example 3: Custom error UI
+export function CustomErrorBoundary({ children }: { children: ReactNode }) {
+  return (
+    <ErrorBoundary
+      fallback={(error, reset) => (
+        <div className="error-container">
+          <h1>Oops!</h1>
+          <p>We encountered an error: {error.message}</p>
+          <button onClick={reset}>Retry</button>
+          <a href="/">Go Home</a>
+        </div>
+      )}
+    >
+      {children}
+    </ErrorBoundary>
+  )
+}
+
+/**
+ * Using throwOnError with Queries
+ *
+ * Queries can throw errors to error boundaries
+ */
+import { useQuery } from '@tanstack/react-query'
+
+// Example 1: Always throw errors
+function UserData({ id }: { id: number }) {
+  const { data } = useQuery({
+    queryKey: ['user', id],
+    queryFn: async () => {
+      const response = await fetch(`/api/users/${id}`)
+      if (!response.ok) throw new Error('User not found')
+      return response.json()
+    },
+    throwOnError: true, // Throw to error boundary
+  })
+
+  return <div>{data.name}</div>
+}
+
+// Example 2: Conditional throwing (only server errors)
+function ConditionalErrorThrowing({ id }: { id: number }) {
+  const { data } = useQuery({
+    queryKey: ['user', id],
+    queryFn: async () => {
+      const response = await fetch(`/api/users/${id}`)
+      if (!response.ok) throw new Error(`HTTP ${response.status}`)
+      return response.json()
+    },
+    throwOnError: (error) => {
+      // Only throw 5xx server errors to boundary
+      // Handle 4xx client errors locally
+      return error.message.includes('5')
+    },
+  })
+
+  return <div>{data?.name ?? 'Not found'}</div>
+}
+
+/**
+ * Multiple Error Boundaries (Layered)
+ *
+ * Place boundaries at different levels for granular error handling
+ */
+export function LayeredErrorBoundaries() {
+  return (
+    // App-level boundary
+    <ErrorBoundary fallback={(error) => <AppCrashScreen error={error} />}>
+      <Header />
+
+      {/* Feature-level boundary */}
+      <ErrorBoundary fallback={(error) => <FeatureError error={error} />}>
+        <UserProfile />
+      </ErrorBoundary>
+
+      {/* Another feature boundary */}
+      <ErrorBoundary>
+        <TodoList />
+      </ErrorBoundary>
+
+      <Footer />
+    </ErrorBoundary>
+  )
+}
+
+/**
+ * Key concepts:
+ *
+ * 1. QueryErrorResetBoundary: Provides reset function for TanStack Query
+ * 2. throwOnError: Makes query throw errors to boundary
+ * 3. Layered boundaries: Isolate failures to specific features
+ * 4. Custom fallbacks: Control error UI per boundary
+ * 5. Error logging: componentDidCatch for monitoring
+ *
+ * Best practices:
+ * ✅ Always wrap app in error boundary
+ * ✅ Use throwOnError for critical errors only
+ * ✅ Provide helpful error messages to users
+ * ✅ Log errors to monitoring service
+ * ✅ Offer reset/retry functionality
+ * ❌ Don't catch all errors - use local error states when appropriate
+ * ❌ Don't throw for expected errors (404, validation)
+ */

package/dist/skills/frameworks/tanstack-query/tanstack-query/templates/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "my-app-with-tanstack-query",
+  "private": true,
+  "version": "1.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc && vite build",
+    "lint": "eslint .",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "@tanstack/react-query": "^5.90.5"
+  },
+  "devDependencies": {
+    "@tanstack/react-query-devtools": "^5.90.2",
+    "@tanstack/eslint-plugin-query": "^5.90.2",
+    "@types/react": "^18.3.12",
+    "@types/react-dom": "^18.3.1",
+    "@typescript-eslint/eslint-plugin": "^8.15.0",
+    "@typescript-eslint/parser": "^8.15.0",
+    "@vitejs/plugin-react": "^4.3.4",
+    "eslint": "^9.16.0",
+    "eslint-plugin-react-hooks": "^5.0.0",
+    "eslint-plugin-react-refresh": "^0.4.16",
+    "typescript": "^5.6.3",
+    "vite": "^6.0.1"
+  }
+}

package/dist/skills/frameworks/tanstack-query/tanstack-query/templates/provider-setup.tsx

@@ -0,0 +1,50 @@
+// src/main.tsx
+import { StrictMode } from 'react'
+import { createRoot } from 'react-dom/client'
+import { QueryClientProvider } from '@tanstack/react-query'
+import { ReactQueryDevtools } from '@tanstack/react-query-devtools'
+import { queryClient } from './lib/query-client'
+import App from './App'
+import './index.css'
+
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <QueryClientProvider client={queryClient}>
+      <App />
+      {/* DevTools are automatically removed in production builds */}
+      <ReactQueryDevtools
+        initialIsOpen={false}
+        buttonPosition="bottom-right"
+        position="bottom"
+      />
+    </QueryClientProvider>
+  </StrictMode>
+)
+
+/**
+ * Important notes:
+ *
+ * 1. QueryClientProvider must wrap all components that use TanStack Query hooks
+ * 2. DevTools must be inside the provider
+ * 3. DevTools are tree-shaken in production (safe to leave in code)
+ * 4. Only create ONE QueryClient instance for entire app (imported from query-client.ts)
+ *
+ * DevTools configuration options:
+ * - initialIsOpen: true/false - Start open or closed
+ * - buttonPosition: "top-left" | "top-right" | "bottom-left" | "bottom-right"
+ * - position: "top" | "bottom" | "left" | "right"
+ * - toggleButtonProps: Custom button styles
+ * - panelProps: Custom panel styles
+ *
+ * Example with custom styles:
+ * <ReactQueryDevtools
+ *   initialIsOpen={false}
+ *   buttonPosition="bottom-right"
+ *   toggleButtonProps={{
+ *     style: { marginBottom: '4rem' }
+ *   }}
+ *   panelProps={{
+ *     style: { height: '500px' }
+ *   }}
+ * />
+ */

package/dist/skills/frameworks/tanstack-query/tanstack-query/templates/query-client-config.ts

@@ -0,0 +1,72 @@
+// src/lib/query-client.ts
+import { QueryClient } from '@tanstack/react-query'
+
+/**
+ * QueryClient configuration for TanStack Query v5
+ *
+ * Key settings:
+ * - staleTime: How long data is fresh (won't refetch)
+ * - gcTime: How long inactive data stays in cache (garbage collection time)
+ * - retry: Number of retry attempts on failure
+ * - refetchOnWindowFocus: Refetch when window regains focus
+ */
+export const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      // Data is fresh for 5 minutes (won't refetch during this time)
+      staleTime: 1000 * 60 * 5,
+
+      // Inactive data stays in cache for 1 hour before garbage collection
+      gcTime: 1000 * 60 * 60,
+
+      // Retry failed requests with smart logic
+      retry: (failureCount, error) => {
+        // Don't retry on 404s
+        if (error instanceof Response && error.status === 404) {
+          return false
+        }
+        // Retry up to 3 times for other errors
+        return failureCount < 3
+      },
+
+      // Don't refetch on window focus (can be annoying during dev)
+      // Set to true for real-time data (stock prices, notifications)
+      refetchOnWindowFocus: false,
+
+      // Refetch when network reconnects
+      refetchOnReconnect: true,
+
+      // Refetch on component mount if data is stale
+      refetchOnMount: true,
+    },
+    mutations: {
+      // Don't retry mutations by default (usually not wanted)
+      retry: 0,
+
+      // Global mutation error handler (optional)
+      onError: (error) => {
+        console.error('Mutation error:', error)
+        // Add global error handling here (toast, alert, etc.)
+      },
+    },
+  },
+})
+
+/**
+ * Adjust these settings based on your needs:
+ *
+ * For real-time data (stock prices, notifications):
+ * - staleTime: 0 (always stale, refetch frequently)
+ * - refetchOnWindowFocus: true
+ * - refetchInterval: 1000 * 30 (refetch every 30s)
+ *
+ * For static data (user settings, app config):
+ * - staleTime: Infinity (never stale)
+ * - refetchOnWindowFocus: false
+ * - refetchOnMount: false
+ *
+ * For moderate data (todos, posts):
+ * - staleTime: 1000 * 60 * 5 (5 minutes)
+ * - refetchOnWindowFocus: false
+ * - refetchOnMount: true
+ */

package/dist/skills/frameworks/tanstack-query/tanstack-query/templates/use-infinite-query.tsx

@@ -0,0 +1,214 @@
+// src/hooks/useInfiniteTodos.ts
+import { useInfiniteQuery } from '@tanstack/react-query'
+import { useEffect, useRef } from 'react'
+import type { Todo } from './useTodos'
+
+/**
+ * Paginated response type
+ */
+type TodosPage = {
+  data: Todo[]
+  nextCursor: number | null
+  previousCursor: number | null
+}
+
+/**
+ * Fetch paginated todos
+ *
+ * In real API: cursor would be offset, page number, or last item ID
+ */
+async function fetchTodosPage({ pageParam }: { pageParam: number }): Promise<TodosPage> {
+  const limit = 20
+  const start = pageParam * limit
+  const end = start + limit
+
+  const response = await fetch(
+    `https://jsonplaceholder.typicode.com/todos?_start=${start}&_limit=${limit}`
+  )
+
+  if (!response.ok) {
+    throw new Error('Failed to fetch todos')
+  }
+
+  const data: Todo[] = await response.json()
+
+  return {
+    data,
+    nextCursor: data.length === limit ? pageParam + 1 : null,
+    previousCursor: pageParam > 0 ? pageParam - 1 : null,
+  }
+}
+
+/**
+ * Infinite query hook
+ *
+ * Usage:
+ * const { data, fetchNextPage, hasNextPage, isFetchingNextPage } = useInfiniteTodos()
+ */
+export function useInfiniteTodos() {
+  return useInfiniteQuery({
+    queryKey: ['todos', 'infinite'],
+    queryFn: fetchTodosPage,
+
+    // v5 REQUIRES initialPageParam (was optional in v4)
+    initialPageParam: 0,
+
+    // Determine if there are more pages
+    getNextPageParam: (lastPage) => lastPage.nextCursor,
+
+    // Optional: Determine if there are previous pages (bidirectional)
+    getPreviousPageParam: (firstPage) => firstPage.previousCursor,
+
+    // How many pages to keep in memory (default: Infinity)
+    maxPages: undefined,
+  })
+}
+
+/**
+ * Component with manual "Load More" button
+ */
+export function InfiniteTodosManual() {
+  const {
+    data,
+    fetchNextPage,
+    hasNextPage,
+    isFetchingNextPage,
+    isPending,
+    isError,
+    error,
+  } = useInfiniteTodos()
+
+  if (isPending) return <div>Loading...</div>
+  if (isError) return <div>Error: {error.message}</div>
+
+  return (
+    <div>
+      <h1>Infinite Todos (Manual)</h1>
+
+      {/* Render all pages */}
+      {data.pages.map((page, i) => (
+        <div key={i}>
+          <h2>Page {i + 1}</h2>
+          <ul>
+            {page.data.map((todo) => (
+              <li key={todo.id}>
+                <input type="checkbox" checked={todo.completed} readOnly />
+                {todo.title}
+              </li>
+            ))}
+          </ul>
+        </div>
+      ))}
+
+      {/* Load more button */}
+      <button
+        onClick={() => fetchNextPage()}
+        disabled={!hasNextPage || isFetchingNextPage}
+      >
+        {isFetchingNextPage
+          ? 'Loading more...'
+          : hasNextPage
+          ? 'Load More'
+          : 'No more todos'}
+      </button>
+    </div>
+  )
+}
+
+/**
+ * Component with automatic infinite scroll
+ * Uses Intersection Observer to detect when user scrolls to bottom
+ */
+export function InfiniteTodosAuto() {
+  const {
+    data,
+    fetchNextPage,
+    hasNextPage,
+    isFetchingNextPage,
+    isPending,
+    isError,
+    error,
+  } = useInfiniteTodos()
+
+  const loadMoreRef = useRef<HTMLDivElement>(null)
+
+  // Intersection Observer for automatic loading
+  useEffect(() => {
+    const observer = new IntersectionObserver(
+      (entries) => {
+        // When sentinel element is visible and there are more pages
+        if (entries[0].isIntersecting && hasNextPage && !isFetchingNextPage) {
+          fetchNextPage()
+        }
+      },
+      { threshold: 0.1 } // Trigger when 10% of element is visible
+    )
+
+    if (loadMoreRef.current) {
+      observer.observe(loadMoreRef.current)
+    }
+
+    return () => {
+      observer.disconnect()
+    }
+  }, [fetchNextPage, hasNextPage, isFetchingNextPage])
+
+  if (isPending) return <div>Loading...</div>
+  if (isError) return <div>Error: {error.message}</div>
+
+  return (
+    <div>
+      <h1>Infinite Todos (Auto)</h1>
+
+      {/* Render all pages */}
+      {data.pages.map((page, i) => (
+        <div key={i}>
+          {page.data.map((todo) => (
+            <div key={todo.id}>
+              <input type="checkbox" checked={todo.completed} readOnly />
+              {todo.title}
+            </div>
+          ))}
+        </div>
+      ))}
+
+      {/* Sentinel element - triggers loading when scrolled into view */}
+      <div ref={loadMoreRef}>
+        {isFetchingNextPage ? (
+          <div>Loading more...</div>
+        ) : hasNextPage ? (
+          <div>Scroll to load more</div>
+        ) : (
+          <div>No more todos</div>
+        )}
+      </div>
+    </div>
+  )
+}
+
+/**
+ * Key concepts:
+ *
+ * 1. data.pages: Array of all fetched pages
+ * 2. fetchNextPage(): Loads next page
+ * 3. hasNextPage: Boolean if more pages available
+ * 4. isFetchingNextPage: Loading state for next page
+ * 5. initialPageParam: Starting cursor (REQUIRED in v5)
+ * 6. getNextPageParam: Function returning next cursor or null
+ *
+ * Access all data:
+ * const allTodos = data.pages.flatMap(page => page.data)
+ *
+ * Bidirectional scrolling:
+ * - Add getPreviousPageParam
+ * - Use fetchPreviousPage() and hasPreviousPage
+ *
+ * Performance:
+ * - Use maxPages to limit memory (e.g., maxPages: 10)
+ * - Old pages are garbage collected automatically
+ *
+ * Common patterns:
+ * - Manual: Load More button
+ * - Auto: Intersection Observer
+ * - Virtualized: react-window or react-virtual for huge lists
+ */