@minhduydev/mdpi 0.4.1 → 0.5.0

package/dist/template/.pi/skills/nextjs-cache/SKILL.md

@@ -0,0 +1,262 @@
+---
+name: nextjs-cache
+description: Use when working with Next.js 16 caching — `use cache` directive, cacheLife, cacheTag, revalidation, migration from v15. MUST load before implementing any caching strategy.
+---
+
+# Next.js Cache System (Next.js 16)
+
+## When to Use
+
+- Adding `use cache` to functions or components
+- Configuring cache lifetimes with `cacheLife()`
+- Tagging cache entries for targeted revalidation
+- Migrating from Next.js 15's implicit cache (force-dynamic, fetch cache)
+- Calling `revalidateTag()` / `revalidatePath()` after mutations
+- Using `connection()` for database-aware caching
+
+## When NOT to Use
+
+- Pages Router projects (no `use cache` support)
+- Next.js 14 or earlier (different cache model)
+- Purely client-side caching (use TanStack Query or SWR)
+
+## Core Pattern: `use cache`
+
+```tsx
+// app/lib/data.ts
+import { cacheTag } from 'next/cache'
+import { db } from '@/lib/db'
+
+export async function getPosts() {
+  'use cache'
+  cacheTag('posts')  // Tag for later revalidation
+
+  const posts = await db.post.findMany({
+    include: { author: true },
+    orderBy: { createdAt: 'desc' },
+  })
+
+  return posts
+}
+```
+
+```tsx
+// app/posts/page.tsx
+import { getPosts } from '@/lib/data'
+
+export default async function PostsPage() {
+  const posts = await getPosts()  // Cached until revalidated or expired
+  return <PostsList posts={posts} />
+}
+```
+
+## cacheLife — Set TTL
+
+```tsx
+import { cacheLife } from 'next/cache'
+
+export async function getPopularPosts() {
+  'use cache'
+  cacheLife('hours')  // Revalidate every hour
+  cacheTag('popular-posts')
+
+  return db.post.findMany({ where: { views: { gte: 1000 } } })
+}
+```
+
+Available `cacheLife` values:
+
+| Profile | Duration | Use Case |
+|---------|----------|----------|
+| `'seconds'` | ~1 second | Real-time but deduped |
+| `'minutes'` | ~5 minutes | Frequently changing data |
+| `'hours'` | ~1 hour | Dashboard stats, user profiles |
+| `'days'` | ~1 day | Blog content, static pages |
+| `'weeks'` | ~1 week | Changelogs, documentation |
+| `'max'` | Unlimited | Immutable data (never revalidates automatically) |
+
+Custom profiles via `next.config.ts`:
+
+```ts
+// next.config.ts
+import type { NextConfig } from 'next'
+
+const config: NextConfig = {
+  cacheLife: {
+    frequent: {
+      stale: 60,       // seconds before background revalidate
+      revalidate: 300, // seconds before full re-fetch
+      expire: 3600,    // seconds before purge
+    },
+  },
+}
+```
+
+## cacheTag — Target Revalidation
+
+```tsx
+// Tag multiple related caches
+export async function getPost(id: string) {
+  'use cache'
+  cacheTag(`post-${id}`, 'posts')  // Individual + list tag
+
+  return db.post.findUnique({ where: { id } })
+}
+```
+
+```tsx
+// app/actions.ts — revalidate after mutation
+'use server'
+
+import { revalidateTag, revalidatePath } from 'next/cache'
+
+export async function deletePost(id: string) {
+  await db.post.delete({ where: { id } })
+
+  revalidateTag(`post-${id}`)  // Revalidate specific post
+  revalidateTag('posts')       // Revalidate all post lists
+  revalidatePath('/posts')     // Also revalidate the URL path
+}
+```
+
+## connection() — Database-Driven Cache
+
+`connection()` makes the cache aware of your database connection, speeding up purge:
+
+```tsx
+import { connection } from 'next/cache'
+
+export async function getPost(id: string) {
+  'use cache'
+  cacheTag(`post-${id}`)
+  connection()  // Invalidate when DB connection changes (e.g., deploy)
+
+  return db.post.findUnique({ where: { id } })
+}
+```
+
+Call `connection()` at any point in the cached function. Multiple calls deduplicate.
+
+## Cacheable vs Non-Cacheable
+
+**Can be cached**: Database queries, filesystem reads, fetch to stable APIs, computed values, Component output.
+
+**Cannot be cached**: Request objects (`cookies()`, `headers()`), mutable state, random values, real-time data.
+
+```tsx
+export async function getUserData() {
+  const session = await auth()  // ❌ Uses cookies — cannot cache
+
+  const user = await db.user.findUnique({
+    where: { id: session.userId }
+  })
+
+  return user
+}
+```
+
+**Solution**: Split the function — cache only the data part:
+
+```tsx
+export async function getUserData() {
+  const session = await auth()  // Not cached
+
+  return getUser(session.userId)  // Cached
+}
+
+async function getUser(id: string) {
+  'use cache'
+  cacheTag(`user-${id}`)
+  return db.user.findUnique({ where: { id } })
+}
+```
+
+## Migration from Next.js 15
+
+### Before (v15 implicit caching):
+
+```tsx
+// Next.js 15
+export const dynamic = 'force-dynamic'     // Opt out of caching
+export const revalidate = 3600             // ISR interval
+
+// fetch caching
+const data = await fetch(url, { cache: 'no-store' })
+const data = await fetch(url, { next: { revalidate: 60 } })
+```
+
+### After (v16 explicit caching):
+
+```tsx
+// Next.js 16 — everything is dynamic by default
+// To cache, use `use cache`:
+export async function getPage() {
+  'use cache'
+  cacheLife('hours')
+  return db.page.findMany()
+}
+
+// No more fetch cache options — use cache instead:
+const data = await fetch(url)  // Always fresh, unless wrapped in use cache
+```
+
+### Quick Migration Table
+
+| v15 Pattern | v16 Equivalent |
+|------------|----------------|
+| `fetch(url, { cache: 'no-store' })` | `fetch(url)` — no cache (default) |
+| `fetch(url, { next: { revalidate: 60 } })` | Wrap in `use cache` + `cacheLife` |
+| `export const dynamic = 'force-dynamic'` | Remove — dynamic is default |
+| `export const revalidate = 3600` | `'use cache'` + `cacheLife('hours')` |
+| `revalidatePath('/posts')` | Same API — still works |
+| `revalidateTag('posts')` | Same API — still works with `cacheTag` |
+| `unstable_cache(fn, ['key'])` | `'use cache'` + `cacheTag('key')` |
+
+## Revalidation vs Expiration
+
+- **Revalidate** (`revalidateTag`/`revalidatePath`): Immediate purge and re-fetch on next request
+- **Expire** (`cacheLife` TTL): Background revalidate, stale data served until fresh data ready
+
+```tsx
+// Mutation pattern — revalidate affected caches
+export async function updatePost(id: string, data: PostInput) {
+  await db.post.update({ where: { id }, data })
+
+  revalidateTag(`post-${id}`)           // Immediate purge
+  // cacheLife handles TTL-based refresh for other entries
+}
+```
+
+## Concurrent Mutations Safety
+
+`use cache` functions support deduplication — concurrent requests for the same data share one database call:
+
+```tsx
+// Three components call getPosts() on same page
+// → only ONE database query executes
+<PostsList />      // calls getPosts()
+<RecentPosts />    // calls getPosts() — deduped
+<PopularPosts />   // calls getPosts() — deduped
+```
+
+## Common Pitfalls
+
+| Pitfall | Fix |
+|---------|-----|
+| Using `cookies()` inside `'use cache'` | Split function: read cookies outside, pass data into cached function |
+| Forgetting `cacheTag()` | Without tags, cache can only be purged by TTL or full flush |
+| Using `revalidatePath` too broadly | Prefer `revalidateTag` — narrower scope, less CPU |
+| Not invalidating after mutation | Every mutation must revalidate affected caches |
+| `cacheLife` too short for write-heavy data | Use `cacheLife('seconds')` or skip caching for hot data |
+| Caching user-specific data without user-scoping | Include `userId` in `cacheTag`: `cacheTag('user-${id}-posts')` |
+| Assuming cache survives deployment | Add `connection()` to auto-invalidate on deploy |
+
+## Verification
+
+- [ ] `'use cache'` functions have `cacheTag()` for targeted revalidation
+- [ ] Mutations call `revalidateTag()` or `revalidatePath()`
+- [ ] No `cookies()` or `headers()` inside cached functions
+- [ ] `cacheLife` appropriate for data freshness requirements
+- [ ] `connection()` added for database queries that should invalidate on deploy
+- [ ] v15 `fetch` cache options removed or migrated
+- [ ] User-scoped data uses user-specific cache tags

package/dist/template/.pi/skills/react-best-practices/SKILL.md

@@ -7,11 +7,16 @@ description: MUST load when writing, reviewing, or refactoring React/Next.js cod
 
 ## When to Use
 
-- Applying performance guidelines to React/Next.js components or pages.
+- Applying performance guidelines to React 19 / Next.js 16 components or pages.
+- Optimizing Server Components, data fetching, bundle size, and re-renders.
 
 ## When NOT to Use
 
 - Non-React codebases or UI-free/backend-only changes.
+- Server Actions and form patterns (use `react-server-actions` skill)
+- App Router architecture (use `nextjs-app-router` skill)
+- Next.js 16 caching (use `nextjs-cache` skill)
+- State management (use `tanstack-query`, `zustand`, or `react-hook-form` skills)
 
 
 ## When to Apply
@@ -108,6 +113,79 @@ Reference these guidelines when:
 - `advanced-event-handler-refs` - Store event handlers in refs
 - `advanced-use-latest` - useLatest for stable callback refs
 
+## React 19 Patterns
+
+### Server Components: Default Data Flow
+
+React 19 + Next.js App Router defaults to **Server Components**. Keep data fetching on the server:
+
+```tsx
+// ✅ Server Component — fetch data where it lives
+// app/posts/page.tsx
+export default async function PostsPage() {
+  const posts = await db.post.findMany()       // Direct DB access
+  const config = await fetchConfig()           // Private API calls (no CORS)
+
+  return <PostsList posts={posts} config={config} />
+}
+```
+
+Only add `'use client'` at the interactive leaves — push it as deep as possible.
+
+### New Hooks Performance Impact
+
+| Hook | Use Case | Performance Note |
+|------|----------|-----------------|
+| `useOptimistic` | Instant UI feedback | Replaces manual `useState` + revert logic |
+| `useActionState` | Form submissions | Replaces `useFormState` (deprecated) |
+| `useFormStatus` | Pending states | Read from child, not form component |
+| `use()` | Unwrap promises in render | Only in Client Components — Server Components use `await` |
+
+### React Compiler Awareness
+
+The React Compiler (stable, React 19+) auto-memoizes components and hooks. With compiler enabled:
+
+- **Remove** manual `useMemo`, `useCallback`, `memo()` unless truly expensive
+- **Keep** `useRef` (semantic, not memoization)
+- **Keep** `useEffect` for synchronization (compiler doesn't touch effects)
+- See `react-compiler` skill for full migration guide
+
+### `use()` for Client Component Data
+
+```tsx
+'use client'
+
+import { use } from 'react'
+
+function UserProfile({ userPromise }) {
+  const user = use(userPromise)  // Unwrap promise in render
+  return <div>{user.name}</div>
+}
+```
+
+`use()` reads Promises and Context in render without a hook wrapper.
+
+## Next.js 16 Caching
+
+Next.js 16 reversed the v15 caching model — everything is dynamic by default. To cache:
+
+```tsx
+// Cached — uses `use cache` directive
+export async function getPosts() {
+  'use cache'
+  cacheLife('hours')
+  cacheTag('posts')
+  return db.post.findMany()
+}
+
+// Dynamic — no directive (default)
+export async function getUserSession() {
+  return auth()  // Always fresh
+}
+```
+
+**Migration**: Remove `export const dynamic = 'force-dynamic'` (now default). Replace `export const revalidate = 3600` with `'use cache'` + `cacheLife`. See `nextjs-cache` skill for detailed migration.
+
 ## How to Use
 
 Read individual rule files for detailed explanations and code examples:

package/dist/template/.pi/skills/react-compiler/SKILL.md

@@ -0,0 +1,237 @@
+---
+name: react-compiler
+description: Use when enabling, debugging, or optimizing with the React Compiler. Covers what it auto-memoizes, what it can't optimize, ESLint plugin, migration guide, and React DevTools debugging. MUST load before enabling the compiler or diagnosing memoization issues.
+---
+
+# React Compiler (React 19+)
+
+## When to Use
+
+- Enabling the React Compiler in a project
+- Understanding what the compiler does and doesn't optimize
+- Debugging why a component didn't get memoized
+- Diagnosing unexpected re-renders in a compiler-enabled project
+- Deciding between manual `useMemo`/`useCallback` vs letting the compiler handle it
+
+## When NOT to Use
+
+- Non-React projects
+- Debugging runtime rendering issues unrelated to memoization
+- Choosing component architecture (use `react-best-practices` or `deep-module-design`)
+
+## What the React Compiler Does
+
+The React Compiler **auto-memoizes** components and hooks at build time. It eliminates the need for manual `useMemo`, `useCallback`, and `memo()` in most cases.
+
+```tsx
+// Before compiler — manual memoization
+function ExpensiveList({ items }: { items: Item[] }) {
+  const filtered = useMemo(
+    () => items.filter(i => i.active),
+    [items]
+  )
+
+  const handleClick = useCallback((id: string) => {
+    onSelect(id)
+  }, [onSelect])
+
+  return filtered.map(item => (
+    <Item key={item.id} item={item} onClick={handleClick} />
+  ))
+}
+
+// With compiler — writes itself
+function ExpensiveList({ items }: { items: Item[] }) {
+  const filtered = items.filter(i => i.active)
+
+  return filtered.map(item => (
+    <Item key={item.id} item={item} onClick={() => onSelect(item.id)} />
+  ))
+}
+```
+
+## What the Compiler CAN Optimize
+
+| Pattern | How |
+|---------|-----|
+| Components | Auto-wraps with `memo()` equivalent |
+| Props & dependencies | Auto-generates dependency arrays for `useMemo`, `useCallback`, `useEffect` |
+| Inline functions | Auto-memoizes `() => {}` passed as props |
+| Computed values | Auto-wraps expensive computations in `useMemo` |
+| Context reads | Tracks granular context reads — only re-renders when specific field changes |
+| useRef stability | Stabilizes `useRef` references |
+
+## What the Compiler CANNOT Optimize
+
+| Limitation | What to Do |
+|-----------|------------|
+| **Side effects in render** | Fix — compiler bails out on impure renders |
+| **Mutating state directly** | Fix — use setState functions |
+| **Dynamic `key` values from `Math.random()`** | Fix — use stable keys |
+| **Third-party libraries that break Rules of React** | Wait for library updates |
+| **Components with `ref` + mutating `ref.current` in render** | Move mutation to event handler or effect |
+| **Deeply nested context that's read broadly** | Split context or use selectors (Zustand) |
+| **Extremely large dependency arrays (100+ items)** | Restructure: split component or function |
+| **Code using `eval()` or `new Function()`** | Remove dynamic code evaluation |
+
+## Enabling the Compiler
+
+### Next.js (15+)
+
+```bash
+npm install babel-plugin-react-compiler
+```
+
+```ts
+// next.config.ts
+import type { NextConfig } from 'next'
+
+const nextConfig: NextConfig = {
+  experimental: {
+    reactCompiler: true,
+  },
+}
+```
+
+### Vite (React)
+
+```bash
+npm install babel-plugin-react-compiler
+```
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+
+export default defineConfig({
+  plugins: [
+    react({
+      babel: {
+        plugins: [['babel-plugin-react-compiler', { target: '19' }]],
+      },
+    }),
+  ],
+})
+```
+
+## ESLint Plugin
+
+```bash
+npm install eslint-plugin-react-compiler
+```
+
+```json
+// .eslintrc.json
+{
+  "plugins": ["react-compiler"],
+  "rules": {
+    "react-compiler/react-compiler": "error"
+  }
+}
+```
+
+The ESLint plugin detects **Rules of React violations** that would cause the compiler to bail out — catches issues at lint time before they become runtime problems.
+
+## React DevTools Integration
+
+With the compiler enabled, React DevTools shows:
+
+- **"Memo ✨"** badge on auto-memoized components
+- Components that **failed** to compile — shown with a warning badge
+- Why it failed: hover the badge for explanation
+
+Open React DevTools → Components tab → look for ✨ beside component names.
+
+## Migration Guide
+
+### Phase 1: ESLint First (No Compiler)
+
+```bash
+npm install eslint-plugin-react-compiler
+```
+
+Enable only the ESLint rule. Fix all violations. This ensures your code follows Rules of React — a prerequisite for the compiler.
+
+### Phase 2: Enable Compiler on CI
+
+```ts
+// next.config.ts — enable on CI/staging first
+reactCompiler: process.env.CI === 'true'
+```
+
+Run your test suite. Check for behavioral changes.
+
+### Phase 3: Remove Manual Memoization
+
+Once the compiler is stable in production:
+
+```tsx
+// Remove these — compiler handles them:
+// - useMemo for computed values
+// - useCallback for event handlers
+// - React.memo() wrapping
+
+// Keep these — they serve semantic purposes:
+// - useMemo for expensive computations the compiler can't prove
+// - useRef for mutable values
+// - useEffect for synchronization
+```
+
+### Phase 4: Full Production Enable
+
+```ts
+reactCompiler: true
+```
+
+## Gradual Adoption
+
+Enable per-directory via compiler directive comments:
+
+```tsx
+// Opt-in specific files:
+'use memo'
+
+// Opt-out specific files:
+'use no memo'
+```
+
+Use `'use memo'` at the top of a file to enable the compiler for that file only, even if the project-level config is off.
+
+## When to Keep Manual Memoization
+
+Even with the compiler, keep manual memoization for:
+
+- **Truly expensive computations**: The compiler is conservative — if you know something is heavy, `useMemo` makes it explicit
+- **Custom hooks with object returns**: `useMemo` on the return value ensures referential stability
+- **Third-party integration**: When passing objects to non-React libraries that do shallow comparisons
+
+## Common Pitfalls
+
+| Pitfall | Fix |
+|---------|-----|
+| Side effects during render (console.log, date, random) | Move to event handlers or effects |
+| Mutating props or state in render | Use immutable updates |
+| Assuming compiler fixes all performance | Compiler handles memoization only — waterfalls, bundle size, SSR still need attention |
+| Leaving manual memoization everywhere | Remove redundant `useMemo`/`useCallback` — they add noise with no benefit |
+| Not running ESLint plugin before enabling | Run ESLint first and fix all violations — this is the #1 source of compiler bailouts |
+| `useMemo` with empty dependency for object identity | Compiler handles this — remove unless it's truly expensive |
+
+## Integration with Other Skills
+
+| Skill | How Compiler Changes It |
+|-------|------------------------|
+| `react-best-practices` | `rerender-memo`, `rerender-functional-setstate` become unnecessary with compiler |
+| `react-server-actions` | No change — Server Actions don't use compiler |
+| `zustand` | Selective subscriptions still recommended — compiler doesn't replace selectors |
+| `tanstack-query` | No change — data fetching patterns unchanged |
+
+## Verification
+
+- [ ] ESLint plugin enabled and passing with zero violations
+- [ ] Compiler enabled in `next.config.ts` or `vite.config.ts`
+- [ ] React DevTools shows ✨ on auto-memoized components
+- [ ] No unexpected re-renders after enabling (profile with DevTools)
+- [ ] Test suite passes with compiler enabled
+- [ ] Manual `useMemo`/`useCallback` removed where compiler handles them
+- [ ] No side effects in render (build warnings if any)