@heyai-rules/pilo-masterkit 1.2.2 → 2.1.0

package/.agent/skills/nextjs-react-expert/8-advanced-advanced-patterns.md

@@ -1,150 +1,150 @@
-# 8. Advanced Patterns
-
-> **Impact:** VARIABLE
-> **Focus:** Advanced patterns for specific cases that require careful implementation.
-
----
-
-## Overview
-
-This section contains **3 rules** focused on advanced patterns.
-
----
-
-## Rule 8.1: Initialize App Once, Not Per Mount
-
-**Impact:** LOW-MEDIUM  
-**Tags:** initialization, useEffect, app-startup, side-effects  
-
-## Initialize App Once, Not Per Mount
-
-Do not put app-wide initialization that must run once per app load inside `useEffect([])` of a component. Components can remount and effects will re-run. Use a module-level guard or top-level init in the entry module instead.
-
-**Incorrect (runs twice in dev, re-runs on remount):**
-
-```tsx
-function Comp() {
-  useEffect(() => {
-    loadFromStorage()
-    checkAuthToken()
-  }, [])
-
-  // ...
-}
-```
-
-**Correct (once per app load):**
-
-```tsx
-let didInit = false
-
-function Comp() {
-  useEffect(() => {
-    if (didInit) return
-    didInit = true
-    loadFromStorage()
-    checkAuthToken()
-  }, [])
-
-  // ...
-}
-```
-
-Reference: [Initializing the application](https://react.dev/learn/you-might-not-need-an-effect#initializing-the-application)
-
----
-
-## Rule 8.2: Store Event Handlers in Refs
-
-**Impact:** LOW  
-**Tags:** advanced, hooks, refs, event-handlers, optimization  
-
-## Store Event Handlers in Refs
-
-Store callbacks in refs when used in effects that shouldn't re-subscribe on callback changes.
-
-**Incorrect (re-subscribes on every render):**
-
-```tsx
-function useWindowEvent(event: string, handler: (e) => void) {
-  useEffect(() => {
-    window.addEventListener(event, handler)
-    return () => window.removeEventListener(event, handler)
-  }, [event, handler])
-}
-```
-
-**Correct (stable subscription):**
-
-```tsx
-function useWindowEvent(event: string, handler: (e) => void) {
-  const handlerRef = useRef(handler)
-  useEffect(() => {
-    handlerRef.current = handler
-  }, [handler])
-
-  useEffect(() => {
-    const listener = (e) => handlerRef.current(e)
-    window.addEventListener(event, listener)
-    return () => window.removeEventListener(event, listener)
-  }, [event])
-}
-```
-
-**Alternative: use `useEffectEvent` if you're on latest React:**
-
-```tsx
-import { useEffectEvent } from 'react'
-
-function useWindowEvent(event: string, handler: (e) => void) {
-  const onEvent = useEffectEvent(handler)
-
-  useEffect(() => {
-    window.addEventListener(event, onEvent)
-    return () => window.removeEventListener(event, onEvent)
-  }, [event])
-}
-```
-
-`useEffectEvent` provides a cleaner API for the same pattern: it creates a stable function reference that always calls the latest version of the handler.
-
----
-
-## Rule 8.3: useEffectEvent for Stable Callback Refs
-
-**Impact:** LOW  
-**Tags:** advanced, hooks, useEffectEvent, refs, optimization  
-
-## useEffectEvent for Stable Callback Refs
-
-Access latest values in callbacks without adding them to dependency arrays. Prevents effect re-runs while avoiding stale closures.
-
-**Incorrect (effect re-runs on every callback change):**
-
-```tsx
-function SearchInput({ onSearch }: { onSearch: (q: string) => void }) {
-  const [query, setQuery] = useState('')
-
-  useEffect(() => {
-    const timeout = setTimeout(() => onSearch(query), 300)
-    return () => clearTimeout(timeout)
-  }, [query, onSearch])
-}
-```
-
-**Correct (using React's useEffectEvent):**
-
-```tsx
-import { useEffectEvent } from 'react';
-
-function SearchInput({ onSearch }: { onSearch: (q: string) => void }) {
-  const [query, setQuery] = useState('')
-  const onSearchEvent = useEffectEvent(onSearch)
-
-  useEffect(() => {
-    const timeout = setTimeout(() => onSearchEvent(query), 300)
-    return () => clearTimeout(timeout)
-  }, [query])
-}
-```
-
+# 8. Advanced Patterns
+
+> **Impact:** VARIABLE
+> **Focus:** Advanced patterns for specific cases that require careful implementation.
+
+---
+
+## Overview
+
+This section contains **3 rules** focused on advanced patterns.
+
+---
+
+## Rule 8.1: Initialize App Once, Not Per Mount
+
+**Impact:** LOW-MEDIUM  
+**Tags:** initialization, useEffect, app-startup, side-effects  
+
+## Initialize App Once, Not Per Mount
+
+Do not put app-wide initialization that must run once per app load inside `useEffect([])` of a component. Components can remount and effects will re-run. Use a module-level guard or top-level init in the entry module instead.
+
+**Incorrect (runs twice in dev, re-runs on remount):**
+
+```tsx
+function Comp() {
+  useEffect(() => {
+    loadFromStorage()
+    checkAuthToken()
+  }, [])
+
+  // ...
+}
+```
+
+**Correct (once per app load):**
+
+```tsx
+let didInit = false
+
+function Comp() {
+  useEffect(() => {
+    if (didInit) return
+    didInit = true
+    loadFromStorage()
+    checkAuthToken()
+  }, [])
+
+  // ...
+}
+```
+
+Reference: [Initializing the application](https://react.dev/learn/you-might-not-need-an-effect#initializing-the-application)
+
+---
+
+## Rule 8.2: Store Event Handlers in Refs
+
+**Impact:** LOW  
+**Tags:** advanced, hooks, refs, event-handlers, optimization  
+
+## Store Event Handlers in Refs
+
+Store callbacks in refs when used in effects that shouldn't re-subscribe on callback changes.
+
+**Incorrect (re-subscribes on every render):**
+
+```tsx
+function useWindowEvent(event: string, handler: (e) => void) {
+  useEffect(() => {
+    window.addEventListener(event, handler)
+    return () => window.removeEventListener(event, handler)
+  }, [event, handler])
+}
+```
+
+**Correct (stable subscription):**
+
+```tsx
+function useWindowEvent(event: string, handler: (e) => void) {
+  const handlerRef = useRef(handler)
+  useEffect(() => {
+    handlerRef.current = handler
+  }, [handler])
+
+  useEffect(() => {
+    const listener = (e) => handlerRef.current(e)
+    window.addEventListener(event, listener)
+    return () => window.removeEventListener(event, listener)
+  }, [event])
+}
+```
+
+**Alternative: use `useEffectEvent` if you're on latest React:**
+
+```tsx
+import { useEffectEvent } from 'react'
+
+function useWindowEvent(event: string, handler: (e) => void) {
+  const onEvent = useEffectEvent(handler)
+
+  useEffect(() => {
+    window.addEventListener(event, onEvent)
+    return () => window.removeEventListener(event, onEvent)
+  }, [event])
+}
+```
+
+`useEffectEvent` provides a cleaner API for the same pattern: it creates a stable function reference that always calls the latest version of the handler.
+
+---
+
+## Rule 8.3: useEffectEvent for Stable Callback Refs
+
+**Impact:** LOW  
+**Tags:** advanced, hooks, useEffectEvent, refs, optimization  
+
+## useEffectEvent for Stable Callback Refs
+
+Access latest values in callbacks without adding them to dependency arrays. Prevents effect re-runs while avoiding stale closures.
+
+**Incorrect (effect re-runs on every callback change):**
+
+```tsx
+function SearchInput({ onSearch }: { onSearch: (q: string) => void }) {
+  const [query, setQuery] = useState('')
+
+  useEffect(() => {
+    const timeout = setTimeout(() => onSearch(query), 300)
+    return () => clearTimeout(timeout)
+  }, [query, onSearch])
+}
+```
+
+**Correct (using React's useEffectEvent):**
+
+```tsx
+import { useEffectEvent } from 'react';
+
+function SearchInput({ onSearch }: { onSearch: (q: string) => void }) {
+  const [query, setQuery] = useState('')
+  const onSearchEvent = useEffectEvent(onSearch)
+
+  useEffect(() => {
+    const timeout = setTimeout(() => onSearchEvent(query), 300)
+    return () => clearTimeout(timeout)
+  }, [query])
+}
+```
+

package/.agent/skills/nextjs-react-expert/9-cache-components.md

@@ -1,103 +1,103 @@
-# Cache Components: `use cache` & `cacheLife`
-
-> [!IMPORTANT]
-> This is a Next.js 16+ specific skill. Do NOT apply these patterns to Next.js 15 or earlier without explicitly checking compatibility.
-
-## Core Philosophy
-Next.js 16 marks the transition from "Segment-level caching" to "Component-level caching". We no longer rely on `export const revalidate = 3600`. Instead, we use granular directives and profiles.
-
-## 1. The `use cache` Directive
-The `use cache` directive can be applied to **Server Components** or **Functions**.
-
-### Rule: Granular Application
-Wrap only the data-fetching logic or the specific component that needs caching.
-
-```tsx
-// Good: Granular function caching
-async function getProduct(id: string) {
-  'use cache'
-  return await db.product.findUnique({ where: { id } })
-}
-
-// Good: Component-level caching
-export default async function ProductCard({ id }: { id: string }) {
-  'use cache'
-  const product = await getProduct(id)
-  return <div>{product.name}</div>
-}
-```
-
-## 2. Using `cacheLife`
-`cacheLife` defines the "Freshness" and "Staleness" of a cached item using pre-defined or custom profiles.
-
-### Usage Pattern
-```tsx
-import { cacheLife } from 'next/cache'
-
-async function getStockInfo() {
-  'use cache'
-  cacheLife('minutes') // Using a pre-defined profile
-  return await fetchStocks()
-}
-```
-
-### Profile Reference
-- `default`: Base profile (1 year stale time).
-- `seconds`: High-frequency updates.
-- `minutes`: Standard dynamic content.
-- `hours`: Stable content (e.g., blog posts).
-- `days`: Semi-static content.
-- `weeks`: Static-like content.
-- `max`: Permanent cache until invalidated.
-
-## 3. On-Demand Invalidation with `cacheTag`
-`cacheTag` allows you to label cached data for selective purging.
-
-### Implementation
-```tsx
-import { cacheTag } from 'next/cache'
-
-async function getProfile(user: string) {
-  'use cache'
-  cacheTag(`profile-${user}`)
-  return await db.user.findUnique(...)
-}
-```
-
-### Revalidation
-In a Server Action:
-```tsx
-import { revalidateTag, updateTag } from 'next/cache'
-
-export async function updateProfile(user: string, data: any) {
-  await db.user.update(...)
-  
-  // Choice A: Background revalidation (Stale-While-Revalidate)
-  revalidateTag(`profile-${user}`)
-  
-  // Choice B: Immediate "Read-Your-Writes" update
-  updateTag(`profile-${user}`)
-}
-```
-
-## 4. Partial Pre-Rendering (PPR)
-Next.js 16 stabilizes PPR via the `cacheComponents` flag in `next.config.ts`. 
-
-### Pattern: Suspense Boundaries
-Always wrap dynamic "Cache Components" in `<Suspense>` to enable PPR.
-
-```tsx
-import { Suspense } from 'react'
-import { Skeleton } from '@/components/ui/skeleton'
-
-export default function Page() {
-  return (
-    <main>
-      <h1>Static Header</h1>
-      <Suspense fallback={<Skeleton />}>
-        <DynamicCacheComponent />
-      </Suspense>
-    </main>
-  )
-}
-```
+# Cache Components: `use cache` & `cacheLife`
+
+> [!IMPORTANT]
+> This is a Next.js 16+ specific skill. Do NOT apply these patterns to Next.js 15 or earlier without explicitly checking compatibility.
+
+## Core Philosophy
+Next.js 16 marks the transition from "Segment-level caching" to "Component-level caching". We no longer rely on `export const revalidate = 3600`. Instead, we use granular directives and profiles.
+
+## 1. The `use cache` Directive
+The `use cache` directive can be applied to **Server Components** or **Functions**.
+
+### Rule: Granular Application
+Wrap only the data-fetching logic or the specific component that needs caching.
+
+```tsx
+// Good: Granular function caching
+async function getProduct(id: string) {
+  'use cache'
+  return await db.product.findUnique({ where: { id } })
+}
+
+// Good: Component-level caching
+export default async function ProductCard({ id }: { id: string }) {
+  'use cache'
+  const product = await getProduct(id)
+  return <div>{product.name}</div>
+}
+```
+
+## 2. Using `cacheLife`
+`cacheLife` defines the "Freshness" and "Staleness" of a cached item using pre-defined or custom profiles.
+
+### Usage Pattern
+```tsx
+import { cacheLife } from 'next/cache'
+
+async function getStockInfo() {
+  'use cache'
+  cacheLife('minutes') // Using a pre-defined profile
+  return await fetchStocks()
+}
+```
+
+### Profile Reference
+- `default`: Base profile (1 year stale time).
+- `seconds`: High-frequency updates.
+- `minutes`: Standard dynamic content.
+- `hours`: Stable content (e.g., blog posts).
+- `days`: Semi-static content.
+- `weeks`: Static-like content.
+- `max`: Permanent cache until invalidated.
+
+## 3. On-Demand Invalidation with `cacheTag`
+`cacheTag` allows you to label cached data for selective purging.
+
+### Implementation
+```tsx
+import { cacheTag } from 'next/cache'
+
+async function getProfile(user: string) {
+  'use cache'
+  cacheTag(`profile-${user}`)
+  return await db.user.findUnique(...)
+}
+```
+
+### Revalidation
+In a Server Action:
+```tsx
+import { revalidateTag, updateTag } from 'next/cache'
+
+export async function updateProfile(user: string, data: any) {
+  await db.user.update(...)
+  
+  // Choice A: Background revalidation (Stale-While-Revalidate)
+  revalidateTag(`profile-${user}`)
+  
+  // Choice B: Immediate "Read-Your-Writes" update
+  updateTag(`profile-${user}`)
+}
+```
+
+## 4. Partial Pre-Rendering (PPR)
+Next.js 16 stabilizes PPR via the `cacheComponents` flag in `next.config.ts`. 
+
+### Pattern: Suspense Boundaries
+Always wrap dynamic "Cache Components" in `<Suspense>` to enable PPR.
+
+```tsx
+import { Suspense } from 'react'
+import { Skeleton } from '@/components/ui/skeleton'
+
+export default function Page() {
+  return (
+    <main>
+      <h1>Static Header</h1>
+      <Suspense fallback={<Skeleton />}>
+        <DynamicCacheComponent />
+      </Suspense>
+    </main>
+  )
+}
+```