@punks/cli 0.1.16 → 1.0.0

package/dist/skills/frameworks/trpc/tanstack-query/templates/custom-hooks-pattern.tsx

@@ -0,0 +1,281 @@
+// src/hooks/useUsers.ts - Example of advanced custom hooks pattern
+import { useQuery, useMutation, useQueryClient, queryOptions } from '@tanstack/react-query'
+
+/**
+ * Type definitions
+ */
+export type User = {
+  id: number
+  name: string
+  email: string
+  phone: string
+}
+
+export type CreateUserInput = Omit<User, 'id'>
+export type UpdateUserInput = Partial<User> & { id: number }
+
+/**
+ * API functions - centralized network logic
+ */
+const userApi = {
+  getAll: async (): Promise<User[]> => {
+    const response = await fetch('https://jsonplaceholder.typicode.com/users')
+    if (!response.ok) throw new Error('Failed to fetch users')
+    return response.json()
+  },
+
+  getById: async (id: number): Promise<User> => {
+    const response = await fetch(`https://jsonplaceholder.typicode.com/users/${id}`)
+    if (!response.ok) throw new Error(`Failed to fetch user ${id}`)
+    return response.json()
+  },
+
+  create: async (user: CreateUserInput): Promise<User> => {
+    const response = await fetch('https://jsonplaceholder.typicode.com/users', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(user),
+    })
+    if (!response.ok) throw new Error('Failed to create user')
+    return response.json()
+  },
+
+  update: async ({ id, ...updates }: UpdateUserInput): Promise<User> => {
+    const response = await fetch(`https://jsonplaceholder.typicode.com/users/${id}`, {
+      method: 'PATCH',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(updates),
+    })
+    if (!response.ok) throw new Error('Failed to update user')
+    return response.json()
+  },
+
+  delete: async (id: number): Promise<void> => {
+    const response = await fetch(`https://jsonplaceholder.typicode.com/users/${id}`, {
+      method: 'DELETE',
+    })
+    if (!response.ok) throw new Error('Failed to delete user')
+  },
+}
+
+/**
+ * Query options factories (v5 best practice)
+ *
+ * Benefits:
+ * - Type-safe reusable query configurations
+ * - DRY principle - single source of truth
+ * - Works with useQuery, useSuspenseQuery, prefetchQuery
+ * - Easier testing and mocking
+ */
+export const usersQueryOptions = queryOptions({
+  queryKey: ['users'],
+  queryFn: userApi.getAll,
+  staleTime: 1000 * 60 * 5, // 5 minutes
+})
+
+export const userQueryOptions = (id: number) =>
+  queryOptions({
+    queryKey: ['users', id],
+    queryFn: () => userApi.getById(id),
+    staleTime: 1000 * 60 * 5,
+  })
+
+/**
+ * Query Hooks
+ */
+export function useUsers() {
+  return useQuery(usersQueryOptions)
+}
+
+export function useUser(id: number) {
+  return useQuery(userQueryOptions(id))
+}
+
+/**
+ * Advanced: Search/Filter Hook
+ *
+ * Demonstrates dependent query with filtering
+ */
+export function useUserSearch(searchTerm: string) {
+  return useQuery({
+    queryKey: ['users', 'search', searchTerm],
+    queryFn: async () => {
+      const users = await userApi.getAll()
+      return users.filter(
+        (user) =>
+          user.name.toLowerCase().includes(searchTerm.toLowerCase()) ||
+          user.email.toLowerCase().includes(searchTerm.toLowerCase())
+      )
+    },
+    enabled: searchTerm.length >= 2, // Only search if 2+ characters
+    staleTime: 1000 * 30, // 30 seconds for search results
+  })
+}
+
+/**
+ * Mutation Hooks
+ */
+export function useCreateUser() {
+  const queryClient = useQueryClient()
+
+  return useMutation({
+    mutationFn: userApi.create,
+    onSuccess: (newUser) => {
+      // Update cache with new user
+      queryClient.setQueryData<User[]>(['users'], (old = []) => [...old, newUser])
+
+      // Invalidate to refetch and ensure consistency
+      queryClient.invalidateQueries({ queryKey: ['users'] })
+    },
+  })
+}
+
+export function useUpdateUser() {
+  const queryClient = useQueryClient()
+
+  return useMutation({
+    mutationFn: userApi.update,
+    onSuccess: (updatedUser) => {
+      // Update individual user cache
+      queryClient.setQueryData(['users', updatedUser.id], updatedUser)
+
+      // Update user in list
+      queryClient.setQueryData<User[]>(['users'], (old = []) =>
+        old.map((user) => (user.id === updatedUser.id ? updatedUser : user))
+      )
+    },
+  })
+}
+
+export function useDeleteUser() {
+  const queryClient = useQueryClient()
+
+  return useMutation({
+    mutationFn: userApi.delete,
+    onSuccess: (_, deletedId) => {
+      // Remove from cache
+      queryClient.setQueryData<User[]>(['users'], (old = []) =>
+        old.filter((user) => user.id !== deletedId)
+      )
+
+      // Remove individual query
+      queryClient.removeQueries({ queryKey: ['users', deletedId] })
+    },
+  })
+}
+
+/**
+ * Advanced: Prefetch Hook
+ *
+ * Prefetch user details on hover for instant navigation
+ */
+export function usePrefetchUser() {
+  const queryClient = useQueryClient()
+
+  return (id: number) => {
+    queryClient.prefetchQuery(userQueryOptions(id))
+  }
+}
+
+/**
+ * Component Usage Examples
+ */
+
+// Example 1: List all users
+export function UserList() {
+  const { data: users, isPending, isError, error } = useUsers()
+  const prefetchUser = usePrefetchUser()
+
+  if (isPending) return <div>Loading...</div>
+  if (isError) return <div>Error: {error.message}</div>
+
+  return (
+    <ul>
+      {users.map((user) => (
+        <li
+          key={user.id}
+          onMouseEnter={() => prefetchUser(user.id)} // Prefetch on hover
+        >
+          <a href={`/users/${user.id}`}>{user.name}</a>
+        </li>
+      ))}
+    </ul>
+  )
+}
+
+// Example 2: User detail page
+export function UserDetail({ id }: { id: number }) {
+  const { data: user, isPending } = useUser(id)
+  const { mutate: updateUser, isPending: isUpdating } = useUpdateUser()
+  const { mutate: deleteUser } = useDeleteUser()
+
+  if (isPending) return <div>Loading...</div>
+  if (!user) return <div>User not found</div>
+
+  return (
+    <div>
+      <h1>{user.name}</h1>
+      <p>Email: {user.email}</p>
+      <p>Phone: {user.phone}</p>
+
+      <button
+        onClick={() => updateUser({ id: user.id, name: 'Updated Name' })}
+        disabled={isUpdating}
+      >
+        Update Name
+      </button>
+
+      <button onClick={() => deleteUser(user.id)}>
+        Delete User
+      </button>
+    </div>
+  )
+}
+
+// Example 3: Search users
+export function UserSearch() {
+  const [search, setSearch] = useState('')
+  const { data: results, isFetching } = useUserSearch(search)
+
+  return (
+    <div>
+      <input
+        type="text"
+        value={search}
+        onChange={(e) => setSearch(e.target.value)}
+        placeholder="Search users..."
+      />
+
+      {isFetching && <span>Searching...</span>}
+
+      {results && (
+        <ul>
+          {results.map((user) => (
+            <li key={user.id}>{user.name} - {user.email}</li>
+          ))}
+        </ul>
+      )}
+    </div>
+  )
+}
+
+/**
+ * Key patterns demonstrated:
+ *
+ * 1. API Layer: Centralized fetch functions
+ * 2. Query Options Factories: Reusable queryOptions
+ * 3. Custom Hooks: Encapsulate query logic
+ * 4. Mutation Hooks: Encapsulate mutation logic
+ * 5. Cache Updates: setQueryData, invalidateQueries, removeQueries
+ * 6. Prefetching: Improve perceived performance
+ * 7. Conditional Queries: enabled option
+ * 8. Search/Filter: Derived queries from base data
+ *
+ * Benefits:
+ * ✅ Type safety throughout
+ * ✅ Easy to test (mock API layer)
+ * ✅ Reusable across components
+ * ✅ Consistent error handling
+ * ✅ Optimized caching strategy
+ * ✅ Better code organization
+ */

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

@@ -0,0 +1,248 @@
+// src/main.tsx - Complete DevTools Setup
+import { StrictMode } from 'react'
+import { createRoot } from 'react-dom/client'
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import { ReactQueryDevtools } from '@tanstack/react-query-devtools'
+import App from './App'
+
+/**
+ * QueryClient with DevTools-friendly configuration
+ */
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      staleTime: 1000 * 60 * 5,
+      gcTime: 1000 * 60 * 60,
+      refetchOnWindowFocus: false,
+    },
+  },
+})
+
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <QueryClientProvider client={queryClient}>
+      <App />
+
+      {/*
+        ReactQueryDevtools Configuration
+
+        IMPORTANT: DevTools are automatically tree-shaken in production
+        Safe to leave in code, won't appear in production bundle
+      */}
+      <ReactQueryDevtools
+        // Start collapsed (default: false)
+        initialIsOpen={false}
+
+        // Button position on screen
+        buttonPosition="bottom-right" // "top-left" | "top-right" | "bottom-left" | "bottom-right"
+
+        // Panel position when open
+        position="bottom" // "top" | "bottom" | "left" | "right"
+
+        // Custom styles for toggle button
+        toggleButtonProps={{
+          style: {
+            marginBottom: '4rem', // Move up if button overlaps content
+            marginRight: '1rem',
+          },
+        }}
+
+        // Custom styles for panel
+        panelProps={{
+          style: {
+            height: '400px', // Custom panel height
+          },
+        }}
+
+        // Add keyboard shortcut (optional)
+        // Default: None, but you can add custom handler
+      />
+    </QueryClientProvider>
+  </StrictMode>
+)
+
+/**
+ * Advanced: Conditional DevTools (explicit dev check)
+ *
+ * DevTools are already removed in production, but can add explicit check
+ */
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <QueryClientProvider client={queryClient}>
+      <App />
+      {import.meta.env.DEV && (
+        <ReactQueryDevtools initialIsOpen={false} />
+      )}
+    </QueryClientProvider>
+  </StrictMode>
+)
+
+/**
+ * Advanced: Custom Toggle Button
+ */
+import { useState } from 'react'
+
+function AppWithCustomDevTools() {
+  const [showDevTools, setShowDevTools] = useState(false)
+
+  return (
+    <QueryClientProvider client={queryClient}>
+      <App />
+
+      {/* Custom toggle button */}
+      <button
+        onClick={() => setShowDevTools(!showDevTools)}
+        style={{
+          position: 'fixed',
+          bottom: '1rem',
+          right: '1rem',
+          zIndex: 99999,
+        }}
+      >
+        {showDevTools ? 'Hide' : 'Show'} DevTools
+      </button>
+
+      {showDevTools && <ReactQueryDevtools initialIsOpen={true} />}
+    </QueryClientProvider>
+  )
+}
+
+/**
+ * DevTools Features (what you can do):
+ *
+ * 1. View all queries: See queryKey, status, data, error
+ * 2. Inspect cache: View cached data for each query
+ * 3. Manual refetch: Force refetch any query
+ * 4. View mutations: See in-flight and completed mutations
+ * 5. Query invalidation: Manually invalidate queries
+ * 6. Explorer mode: Navigate query hierarchy
+ * 7. Time travel: See query state over time
+ * 8. Export state: Download current cache for debugging
+ *
+ * DevTools Panel Sections:
+ * - Queries: All active/cached queries
+ * - Mutations: Recent mutations
+ * - Query Cache: Full cache state
+ * - Mutation Cache: Mutation history
+ * - Settings: DevTools configuration
+ */
+
+/**
+ * Debugging with DevTools
+ */
+
+// Example: Check if query is being cached correctly
+function DebugQueryCaching() {
+  const { data, dataUpdatedAt, isFetching } = useQuery({
+    queryKey: ['todos'],
+    queryFn: fetchTodos,
+  })
+
+  return (
+    <div>
+      <p>Last updated: {new Date(dataUpdatedAt).toLocaleTimeString()}</p>
+      <p>Is fetching: {isFetching ? 'Yes' : 'No'}</p>
+      {/* Open DevTools to see:
+          - Query status (fresh, fetching, stale)
+          - Cache data
+          - Refetch behavior
+      */}
+    </div>
+  )
+}
+
+// Example: Debug why query keeps refetching
+function DebugRefetchingIssue() {
+  const { data, isFetching, isRefetching } = useQuery({
+    queryKey: ['users'],
+    queryFn: fetchUsers,
+    // Check in DevTools if these settings are correct:
+    staleTime: 0, // ❌ Data always stale, will refetch frequently
+    refetchOnWindowFocus: true, // ❌ Refetches on every focus
+    refetchOnMount: true, // ❌ Refetches on every mount
+  })
+
+  // DevTools will show you:
+  // - How many times query refetched
+  // - When it refetched (mount, focus, reconnect)
+  // - Current staleTime and gcTime settings
+
+  return <div>Fetching: {isFetching ? 'Yes' : 'No'}</div>
+}
+
+/**
+ * Production DevTools (optional, separate package)
+ *
+ * For debugging production issues remotely
+ * npm install @tanstack/react-query-devtools-production
+ */
+import { ReactQueryDevtools as ReactQueryDevtoolsProd } from '@tanstack/react-query-devtools-production'
+
+function AppWithProductionDevTools() {
+  const [showDevTools, setShowDevTools] = useState(false)
+
+  useEffect(() => {
+    // Load production devtools on demand
+    // Only when user presses keyboard shortcut or secret URL
+    if (showDevTools) {
+      import('@tanstack/react-query-devtools-production').then((module) => {
+        // Module loaded
+      })
+    }
+  }, [showDevTools])
+
+  return (
+    <QueryClientProvider client={queryClient}>
+      <App />
+      {showDevTools && <ReactQueryDevtoolsProd />}
+    </QueryClientProvider>
+  )
+}
+
+/**
+ * Keyboard Shortcuts (DIY)
+ *
+ * Add custom keyboard shortcut to toggle DevTools
+ */
+function AppWithKeyboardShortcut() {
+  const [showDevTools, setShowDevTools] = useState(false)
+
+  useEffect(() => {
+    const handleKeyPress = (e: KeyboardEvent) => {
+      // Ctrl/Cmd + Shift + D
+      if ((e.ctrlKey || e.metaKey) && e.shiftKey && e.key === 'd') {
+        e.preventDefault()
+        setShowDevTools((prev) => !prev)
+      }
+    }
+
+    window.addEventListener('keydown', handleKeyPress)
+    return () => window.removeEventListener('keydown', handleKeyPress)
+  }, [])
+
+  return (
+    <QueryClientProvider client={queryClient}>
+      <App />
+      {showDevTools && <ReactQueryDevtools />}
+    </QueryClientProvider>
+  )
+}
+
+/**
+ * Best Practices:
+ *
+ * ✅ Keep DevTools in code (tree-shaken in production)
+ * ✅ Start with initialIsOpen={false} to avoid distraction
+ * ✅ Use DevTools to debug cache issues
+ * ✅ Check DevTools when queries refetch unexpectedly
+ * ✅ Export state for bug reports
+ *
+ * ❌ Don't ship production devtools without authentication
+ * ❌ Don't rely on DevTools for production monitoring
+ * ❌ Don't expose sensitive data in cache (use select to filter)
+ *
+ * Performance:
+ * - DevTools have minimal performance impact in dev
+ * - Completely removed in production builds
+ * - No runtime overhead when not open
+ */