initial commit

.agents/skills/tanstack-query-best-practices/rules/cache-gc-time.md

@@ -0,0 +1,93 @@
+# cache-gc-time: Configure gcTime for Inactive Query Retention
+
+## Priority: CRITICAL
+
+## Explanation
+
+`gcTime` (garbage collection time, formerly `cacheTime`) controls how long inactive queries remain in the cache before being garbage collected. Default is 5 minutes. Configure based on your navigation patterns and memory constraints.
+
+## Bad Example
+
+```tsx
+// Not considering gcTime for frequently revisited pages
+const { data } = useQuery({
+  queryKey: ['dashboard-stats'],
+  queryFn: fetchDashboardStats,
+  // Default gcTime of 5 minutes - might be too short for frequently revisited data
+})
+
+// Setting gcTime too high without consideration
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      gcTime: Infinity,  // Never garbage collect - potential memory leak
+    },
+  },
+})
+
+// Setting gcTime to 0 - cache is immediately removed
+const { data } = useQuery({
+  queryKey: ['user-data'],
+  queryFn: fetchUserData,
+  gcTime: 0,  // Loses cache benefits entirely
+})
+```
+
+## Good Example
+
+```tsx
+// Longer gcTime for frequently revisited data
+const { data } = useQuery({
+  queryKey: ['dashboard-stats'],
+  queryFn: fetchDashboardStats,
+  gcTime: 30 * 60 * 1000,  // 30 minutes - user returns to dashboard often
+})
+
+// Shorter gcTime for rarely revisited large data
+const { data: report } = useQuery({
+  queryKey: ['detailed-report', reportId],
+  queryFn: () => fetchReport(reportId),
+  gcTime: 2 * 60 * 1000,  // 2 minutes - large payload, viewed once
+})
+
+// Sensible default with query-specific overrides
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      gcTime: 10 * 60 * 1000,  // 10 minutes default
+    },
+  },
+})
+```
+
+## Understanding gcTime vs staleTime
+
+```
+Query Mount → Data Fresh (staleTime) → Data Stale → Query Unmount → gcTime countdown → Garbage Collected
+
+Timeline example (staleTime: 1min, gcTime: 5min):
+0:00 - Query mounts, fetches data
+0:00-1:00 - Data is fresh (no background refetch)
+1:00+ - Data is stale (background refetch on new mount)
+5:00 - User navigates away, query unmounts
+5:00-10:00 - Data in cache but inactive (gcTime countdown)
+10:00 - Data garbage collected (next mount = full loading state)
+```
+
+## Recommended gcTime Values
+
+| Scenario | gcTime | Rationale |
+|----------|--------|-----------|
+| Frequently revisited routes | 15 - 30min | Instant navigation |
+| Detail pages (viewed once) | 2 - 5min | Memory efficient |
+| Large payloads | 1 - 2min | Prevent memory bloat |
+| Critical user data | 30min+ | Offline-like experience |
+| SSR hydration | >= 2s | Prevent hydration issues |
+
+## Context
+
+- gcTime countdown starts when ALL query observers unmount
+- Remounting before gcTime expires returns cached data instantly
+- Setting gcTime < staleTime is rarely useful
+- For SSR, avoid gcTime: 0 (use minimum 2000ms to allow hydration)
+- Monitor memory usage in long-running applications