@codihaus/claude-skills 1.0.0

package/skills/dev-coding-frontend/references/nextjs.md

@@ -0,0 +1,477 @@
+# Next.js Best Practices
+
+Performance optimization patterns for Next.js App Router applications.
+
+## Rule Categories by Priority
+
+| Priority | Category | Impact |
+|----------|----------|--------|
+| 1 | Eliminating Waterfalls | CRITICAL |
+| 2 | Bundle Optimization | CRITICAL |
+| 3 | Server Components | HIGH |
+| 4 | Client Components | MEDIUM-HIGH |
+| 5 | Re-render Optimization | MEDIUM |
+
+---
+
+## 1. Eliminating Waterfalls (CRITICAL)
+
+### Parallel Data Fetching
+
+**Bad (sequential, 3 round trips):**
+```typescript
+const user = await fetchUser()
+const posts = await fetchPosts()
+const comments = await fetchComments()
+```
+
+**Good (parallel, 1 round trip):**
+```typescript
+const [user, posts, comments] = await Promise.all([
+  fetchUser(),
+  fetchPosts(),
+  fetchComments()
+])
+```
+
+### Move Await Into Branches
+
+**Bad (always waits):**
+```typescript
+async function getUser(id: string, options?: { includeProfile: boolean }) {
+  const user = await db.user.findUnique({ where: { id } })
+  const profile = await db.profile.findUnique({ where: { userId: id } })
+
+  if (options?.includeProfile) {
+    return { ...user, profile }
+  }
+  return user
+}
+```
+
+**Good (only waits when needed):**
+```typescript
+async function getUser(id: string, options?: { includeProfile: boolean }) {
+  const user = await db.user.findUnique({ where: { id } })
+
+  if (options?.includeProfile) {
+    const profile = await db.profile.findUnique({ where: { userId: id } })
+    return { ...user, profile }
+  }
+  return user
+}
+```
+
+### Use Suspense Boundaries
+
+```tsx
+// Stream content as it loads
+export default function Page() {
+  return (
+    <div>
+      <Header />
+      <Suspense fallback={<PostsSkeleton />}>
+        <Posts />
+      </Suspense>
+      <Suspense fallback={<CommentsSkeleton />}>
+        <Comments />
+      </Suspense>
+    </div>
+  )
+}
+```
+
+---
+
+## 2. Bundle Optimization (CRITICAL)
+
+### Avoid Barrel File Imports
+
+Barrel files (index.js re-exports) load thousands of unused modules.
+
+**Bad (imports entire library):**
+```tsx
+import { Check, X, Menu } from 'lucide-react'
+// Loads 1,583 modules, 200-800ms runtime cost
+```
+
+**Good (direct imports):**
+```tsx
+import Check from 'lucide-react/dist/esm/icons/check'
+import X from 'lucide-react/dist/esm/icons/x'
+```
+
+**Alternative (Next.js 13.5+):**
+```js
+// next.config.js
+module.exports = {
+  experimental: {
+    optimizePackageImports: ['lucide-react', '@mui/material']
+  }
+}
+```
+
+### Dynamic Imports for Heavy Components
+
+```tsx
+import dynamic from 'next/dynamic'
+
+// Only load when needed
+const HeavyChart = dynamic(() => import('@/components/Chart'), {
+  loading: () => <ChartSkeleton />,
+  ssr: false // If client-only
+})
+```
+
+### Defer Third-Party Scripts
+
+```tsx
+// Load after hydration
+useEffect(() => {
+  import('analytics').then(({ init }) => init())
+}, [])
+
+// Or use next/script
+<Script src="analytics.js" strategy="afterInteractive" />
+```
+
+---
+
+## 3. Server Components (HIGH)
+
+### Default to Server Components
+
+```tsx
+// app/posts/page.tsx - Server Component (default)
+export default async function PostsPage() {
+  const posts = await getPosts() // Direct DB access
+  return <PostList posts={posts} />
+}
+```
+
+### Use React.cache() for Deduplication
+
+```typescript
+import { cache } from 'react'
+
+export const getCurrentUser = cache(async () => {
+  const session = await auth()
+  if (!session?.user?.id) return null
+  return await db.user.findUnique({
+    where: { id: session.user.id }
+  })
+})
+
+// Multiple components can call getCurrentUser()
+// Only runs once per request
+```
+
+**Important:** Use primitives as arguments, not objects:
+
+```typescript
+// Bad - always cache miss (new object each call)
+const getUser = cache(async (params: { uid: number }) => {...})
+
+// Good - cache hit on same value
+const getUser = cache(async (uid: number) => {...})
+```
+
+### Minimize Client Component Data
+
+```tsx
+// Bad - sends entire user object to client
+<ClientComponent user={user} />
+
+// Good - send only needed fields
+<ClientComponent userName={user.name} userAvatar={user.avatar} />
+```
+
+### Parallel Server Fetching
+
+```tsx
+// Bad - sequential in parent
+async function Page() {
+  const user = await getUser()
+  const posts = await getPosts()
+  return <Content user={user} posts={posts} />
+}
+
+// Good - parallel in children
+async function Page() {
+  return (
+    <>
+      <UserSection />  {/* fetches user */}
+      <PostsSection /> {/* fetches posts in parallel */}
+    </>
+  )
+}
+```
+
+---
+
+## 4. Client Components (MEDIUM-HIGH)
+
+### Mark Client Components Explicitly
+
+```tsx
+'use client'
+
+import { useState } from 'react'
+
+export function Counter() {
+  const [count, setCount] = useState(0)
+  return <button onClick={() => setCount(c => c + 1)}>{count}</button>
+}
+```
+
+### Use SWR for Client Data Fetching
+
+```tsx
+'use client'
+
+import useSWR from 'swr'
+
+export function UserProfile({ userId }: { userId: string }) {
+  const { data, error, isLoading } = useSWR(
+    `/api/users/${userId}`,
+    fetcher
+  )
+
+  if (isLoading) return <Skeleton />
+  if (error) return <Error message={error.message} />
+  return <Profile user={data} />
+}
+```
+
+### Deduplicate Event Listeners
+
+```tsx
+// Bad - each component adds listener
+function Component() {
+  useEffect(() => {
+    window.addEventListener('resize', handleResize)
+    return () => window.removeEventListener('resize', handleResize)
+  }, [])
+}
+
+// Good - shared hook with single listener
+const useWindowSize = create(() => {
+  // Single listener shared across all components
+})
+```
+
+---
+
+## 5. Re-render Optimization (MEDIUM)
+
+### Don't Subscribe to Unused State
+
+```tsx
+// Bad - re-renders on every position change
+function ClickHandler() {
+  const position = useMousePosition()
+  return <button onClick={() => console.log(position)}>Log</button>
+}
+
+// Good - no subscription, read on demand
+function ClickHandler() {
+  const getPosition = useMousePositionRef()
+  return <button onClick={() => console.log(getPosition())}>Log</button>
+}
+```
+
+### Use Primitive Dependencies
+
+```tsx
+// Bad - effect runs on every render (new object)
+useEffect(() => {
+  fetch(`/api/user/${user.id}`)
+}, [user])
+
+// Good - effect runs only when id changes
+useEffect(() => {
+  fetch(`/api/user/${userId}`)
+}, [userId])
+```
+
+### Derived State as Booleans
+
+```tsx
+// Bad - re-renders on any cart change
+function CheckoutButton() {
+  const cart = useCart()
+  if (cart.items.length === 0) return null
+  return <Button>Checkout</Button>
+}
+
+// Good - only re-renders when emptiness changes
+function CheckoutButton() {
+  const hasItems = useCartHasItems()
+  if (!hasItems) return null
+  return <Button>Checkout</Button>
+}
+```
+
+### Functional setState for Stable Callbacks
+
+```tsx
+// Bad - new callback each render
+<button onClick={() => setCount(count + 1)}>+1</button>
+
+// Good - stable callback
+<button onClick={() => setCount(c => c + 1)}>+1</button>
+```
+
+### Lazy State Initialization
+
+```tsx
+// Bad - runs expensive function every render
+const [data] = useState(expensiveComputation())
+
+// Good - only runs once
+const [data] = useState(() => expensiveComputation())
+```
+
+---
+
+## 6. Rendering Patterns
+
+### Conditional Rendering
+
+```tsx
+// Bad - can render 0
+{items.length && <List items={items} />}
+
+// Good - explicit boolean
+{items.length > 0 && <List items={items} />}
+
+// Better - ternary
+{items.length > 0 ? <List items={items} /> : null}
+```
+
+### Hoist Static JSX
+
+```tsx
+// Bad - creates new object each render
+function Component() {
+  const icon = <Icon />
+  return <div>{icon}</div>
+}
+
+// Good - stable reference
+const icon = <Icon />
+function Component() {
+  return <div>{icon}</div>
+}
+```
+
+### Content Visibility for Long Lists
+
+```css
+.list-item {
+  content-visibility: auto;
+  contain-intrinsic-size: 0 50px;
+}
+```
+
+---
+
+## 7. Next.js Specific
+
+### Route Handlers
+
+```typescript
+// app/api/users/route.ts
+export async function GET() {
+  const users = await getUsers()
+  return Response.json(users)
+}
+
+export async function POST(request: Request) {
+  const body = await request.json()
+  const user = await createUser(body)
+  return Response.json(user, { status: 201 })
+}
+```
+
+### Metadata
+
+```typescript
+// Static
+export const metadata = {
+  title: 'My Page',
+  description: 'Page description'
+}
+
+// Dynamic
+export async function generateMetadata({ params }) {
+  const post = await getPost(params.id)
+  return { title: post.title }
+}
+```
+
+### Loading & Error States
+
+```tsx
+// app/posts/loading.tsx
+export default function Loading() {
+  return <PostsSkeleton />
+}
+
+// app/posts/error.tsx
+'use client'
+export default function Error({ error, reset }) {
+  return (
+    <div>
+      <p>Something went wrong</p>
+      <button onClick={reset}>Try again</button>
+    </div>
+  )
+}
+```
+
+### Image Optimization
+
+```tsx
+import Image from 'next/image'
+
+<Image
+  src="/hero.jpg"
+  alt="Hero"
+  width={1200}
+  height={600}
+  priority // For above-fold images
+/>
+```
+
+### Link Prefetching
+
+```tsx
+import Link from 'next/link'
+
+<Link href="/about" prefetch={true}>About</Link>
+
+// Prefetch on hover for dynamic routes
+<Link href={`/posts/${id}`} prefetch={false}>
+  Post
+</Link>
+```
+
+---
+
+## Common Gotchas
+
+1. **Server vs Client confusion** - Default is Server, add 'use client' only when needed
+2. **Fetching in useEffect** - Prefer Server Components or SWR
+3. **Barrel imports** - Use optimizePackageImports or direct imports
+4. **Object dependencies** - Use primitives in useEffect/useMemo deps
+5. **Missing Suspense** - Wrap async components for streaming
+6. **Hydration mismatch** - Ensure server/client render same content
+
+---
+
+## References
+
+- [Next.js App Router Docs](https://nextjs.org/docs/app)
+- [React Server Components](https://react.dev/reference/react/use-server)
+- [Vercel React Best Practices](https://github.com/vercel/react-best-practices)