@minhduydev/mdpi 0.4.1 → 0.6.0

package/dist/template/.pi/skills/nextjs-app-router/SKILL.md

@@ -0,0 +1,334 @@
+---
+name: nextjs-app-router
+description: Use when building or refactoring Next.js App Router pages. Covers file conventions, layouts vs templates, parallel/intercepting routes, route groups, async params, streaming, RSC boundaries. MUST load before any App Router architecture work.
+---
+
+# Next.js App Router Patterns (Next.js 15+)
+
+## When to Use
+
+- Building new pages in Next.js App Router
+- Understanding or refactoring App Router file conventions
+- Designing route architecture (parallel routes, intercepting, groups)
+- Setting up layouts, error boundaries, and loading states
+- Making decisions about Server vs Client Components
+
+## When NOT to Use
+
+- Pages Router projects (`pages/` directory — use `react-best-practices`)
+- Non-Next.js React projects (Vite, Remix, React Router)
+- Pure API routes (not page structure)
+
+## File Conventions Reference
+
+| File | Purpose | Runs |
+|------|---------|------|
+| `page.tsx` | Route's unique UI | Server (default) |
+| `layout.tsx` | Shared UI that persists across navigations | Server (default) |
+| `template.tsx` | Shared UI that remounts on navigation | Server (default) |
+| `loading.tsx` | Suspense fallback while page loads | Server (default) |
+| `error.tsx` | Error boundary for the segment | Client |
+| `not-found.tsx` | 404 UI for the segment | Server (default) |
+| `default.tsx` | Fallback for parallel routes | Server (default) |
+| `route.tsx` | API endpoint for the segment | Server |
+
+## Layout vs Template
+
+**Layout**: persists across navigations, state preserved.
+
+```tsx
+// app/dashboard/layout.tsx
+export default function DashboardLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <div>
+      <nav>Sidebar — stays mounted</nav>
+      <main>{children}</main>
+    </div>
+  )
+}
+```
+
+**Template**: remounts on every navigation. Use when you need:
+- Page transitions (AnimatePresence needs remount)
+- `useEffect` that must re-run on navigation
+- Resetting client state between pages
+
+```tsx
+// app/dashboard/template.tsx
+'use client'
+
+import { AnimatePresence, motion } from 'motion/react'
+
+export default function Template({ children }: { children: React.ReactNode }) {
+  return (
+    <AnimatePresence mode="wait">
+      <motion.div
+        key={usePathname()}
+        initial={{ opacity: 0 }}
+        animate={{ opacity: 1 }}
+        exit={{ opacity: 0 }}
+      >
+        {children}
+      </motion.div>
+    </AnimatePresence>
+  )
+}
+```
+
+**Rule**: Layout wraps Template wraps Page: `layout.tsx > template.tsx > page.tsx`
+
+## Route Groups — `(group)/`
+
+Use parentheses to group routes without affecting the URL:
+
+```
+app/
+├── (marketing)/
+│   ├── page.tsx          → /
+│   ├── about/page.tsx    → /about
+│   └── layout.tsx        # Marketing layout
+├── (dashboard)/
+│   ├── dashboard/page.tsx  → /dashboard
+│   └── layout.tsx          # Dashboard layout (different from marketing)
+```
+
+## Parallel Routes — `@folder/`
+
+Render multiple pages in the same layout simultaneously:
+
+```
+app/
+├── dashboard/
+│   ├── layout.tsx        # Accepts both props:
+│   ├── @analytics/       #   children, analytics, team
+│   │   └── page.tsx
+│   ├── @team/
+│   │   └── page.tsx
+│   └── page.tsx          # Default children
+```
+
+```tsx
+// app/dashboard/layout.tsx
+export default function DashboardLayout(props: {
+  children: React.ReactNode
+  analytics: React.ReactNode
+  team: React.ReactNode
+}) {
+  return (
+    <div className="grid grid-cols-2">
+      <div>{props.children}</div>
+      <div>{props.analytics}</div>
+      <div>{props.team}</div>
+    </div>
+  )
+}
+```
+
+Each slot needs a `default.tsx` for initial load and unmatched routes.
+
+## Intercepting Routes — `(.)folder/`
+
+Render a route in the context of another without full navigation:
+
+| Convention | Meaning |
+|-----------|---------|
+| `(.)folder/` | Same level |
+| `(..)folder/` | One level up |
+| `(..)(..)folder/` | Two levels up |
+| `(...)folder/` | From root |
+
+Common pattern: Photo modal:
+
+```
+app/
+├── photos/
+│   ├── page.tsx              # Photos grid: /
+│   └── [id]/
+│       └── page.tsx          # Photo detail: /photos/1
+└── @modal/
+    ├── default.tsx           # null return
+    └── (.)photos/
+        └── [id]/
+            └── page.tsx      # Modal overlay when navigating from photos grid
+```
+
+```tsx
+// app/layout.tsx
+export default function RootLayout({ children, modal }) {
+  return (
+    <>
+      {children}
+      {modal}
+    </>
+  )
+}
+```
+
+## Async Server Components
+
+```tsx
+// app/posts/[id]/page.tsx — no 'use client'
+export default async function PostPage({
+  params,
+}: {
+  params: Promise<{ id: string }>  // params is a Promise in Next.js 15+
+}) {
+  const { id } = await params
+  const post = await db.post.findUnique({ where: { id } })
+
+  return <article>{post.content}</article>
+}
+```
+
+**Next.js 15+**: `params`, `searchParams` are Promises — must `await` them.
+
+## Streaming with Suspense + loading.tsx
+
+```tsx
+// app/posts/page.tsx
+import { Suspense } from 'react'
+
+export default function PostsPage() {
+  return (
+    <div>
+      <h1>Posts</h1>
+      <Suspense fallback={<PostsSkeleton />}>
+        <PostsList />  {/* Streams in when ready */}
+      </Suspense>
+      <Suspense fallback={<StatsSkeleton />}>
+        <PostStats />  {/* Streams independently */}
+      </Suspense>
+    </div>
+  )
+}
+```
+
+- `loading.tsx` wraps the entire page in Suspense automatically
+- Manual `<Suspense>` gives finer control — stream sections independently
+- Wrap data-fetching Server Components in Suspense
+
+## RSC Boundary Rules
+
+```
+Server Component (default)
+  └─ can render → Client Components
+  └─ can pass → serializable props only (no functions, no JSX as props)
+  └─ can use → async/await, direct DB access, filesystem, secrets
+
+Client Component ('use client')
+  └─ can render → Server Components (passed as children)
+  └─ can use → hooks, event handlers, browser APIs, state
+  └─ cannot → async/await directly, access DB
+```
+
+**Boundary pattern** — push 'use client' as deep as possible:
+
+```tsx
+// ✅ Server Component (default) — data fetching here
+export default async function UserProfile({ userId }) {
+  const user = await db.user.findUnique({ where: { id: userId } })
+
+  return (
+    <div>
+      <h1>{user.name}</h1>
+      <EditButton />  {/* Only the interactive leaf is client */}
+    </div>
+  )
+}
+
+// ✅ Client leaf — only what needs interactivity
+'use client'
+function EditButton() {
+  const [open, setOpen] = useState(false)
+  return <button onClick={() => setOpen(true)}>Edit</button>
+}
+```
+
+## Error Handling
+
+```tsx
+// app/dashboard/error.tsx
+'use client'
+
+export default function DashboardError({
+  error,
+  reset,
+}: {
+  error: Error & { digest?: string }
+  reset: () => void
+}) {
+  return (
+    <div>
+      <h2>Something went wrong!</h2>
+      <button onClick={() => reset()}>Try again</button>
+    </div>
+  )
+}
+```
+
+- `error.tsx` must be a Client Component
+- Errors bubble up to the nearest `error.tsx`
+- `reset()` re-renders the error boundary's children
+- `error.tsx` in a nested segment only catches errors in that segment and below
+
+## Middleware
+
+```tsx
+// middleware.ts (root level)
+import { NextResponse } from 'next/server'
+import type { NextRequest } from 'next/server'
+
+export function middleware(request: NextRequest) {
+  const token = request.cookies.get('token')
+
+  // Protect routes
+  if (!token && request.nextUrl.pathname.startsWith('/dashboard')) {
+    return NextResponse.redirect(new URL('/login', request.url))
+  }
+
+  return NextResponse.next()
+}
+
+export const config = {
+  matcher: ['/dashboard/:path*']
+}
+```
+
+## Metadata API
+
+```tsx
+// Static metadata
+export const metadata: Metadata = {
+  title: 'Dashboard',
+  description: 'Manage your account',
+}
+
+// Dynamic metadata (Server Components)
+export async function generateMetadata({ params }): Promise<Metadata> {
+  const post = await getPost(params.id)
+  return { title: post.title, description: post.excerpt }
+}
+```
+
+## Common Pitfalls
+
+| Pitfall | Fix |
+|---------|-----|
+| Adding `'use client'` to a layout | Layouts are Server Components by default; only add `'use client'` when you need hooks |
+| Forgetting `default.tsx` for parallel routes | Every slot needs a `default.tsx` for initial load |
+| Passing functions as props from Server to Client | Functions are not serializable — define them in the client |
+| Using `useSearchParams()` in Server Component | Use `searchParams` prop (Promise in v15+) |
+| `params` treated as plain object (v15+) | `params` is now a Promise — must `await params` |
+| No Suspense boundary for async component | Wrap in `<Suspense>` or ensure `loading.tsx` exists |
+| `layout.tsx` doesn't receive `searchParams` | Only `page.tsx` gets `searchParams` |
+
+## Verification
+
+- [ ] Server Components are the default — `'use client'` only where interactive
+- [ ] `params` and `searchParams` are awaited (Next.js 15+)
+- [ ] Error boundaries (`error.tsx`) exist at appropriate levels
+- [ ] Loading states (`loading.tsx` or `<Suspense>`) for async pages
+- [ ] Parallel route slots each have `default.tsx`
+- [ ] Layout and template used correctly (persist vs remount)
+- [ ] Route groups used to share layouts without affecting URL
+- [ ] Functions and non-serializable data stay in Client Components

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: