nextjs-architecture

Files (1)

• SKILL.md

SKILL.md (first lines)

# Next.js 15 & React Architecture

## Core Architecture
- **Server-First (Composition Pattern)**: Use React Server Components (RSC) by default. Pass data down to Client Components as props to keep the client bundle size near zero.
- **Data Mutations**: Use **Server Actions** for all backend communications. NO API routes (`app/api/...`) unless strictly required for external webhooks.
- **Caching & Fetching**: Utilize Next.js native caching. Avoid `useEffect` for data fetching; use Server Components `await fetch()`.
- **Image/Font Optimization**: Always use `next/image` and `next/font` (Geist) to protect Core Web Vitals. No unoptimized static assets.
- **State Management**: Derive state from props and URL search params before reaching for `useState` or heavy Contexts.

## Golden Rule: Client Components at the "Leaves" of the Tree

In Next.js (with the App Router), the main performance rule is to keep **Client Components as low as possible in the component tree** and let the parents be **Server Components**.

### What are Client Components?
They are React components that render in the user's browser instead of on the server. They are declared by placing the `"use client"` directive on the first line of the file.

### When should you use them?
You should use a Client Component **only when you need interactivity or access to the browser**. If your component doesn't do any of the following, it should be a Server Component:
* **Interactivity and Events:** `onClick`, `onChange`, `onSubmit`, etc.
* **State and Lifecycle:** `useState`, `useEffect`, `useReducer`, `useRef`.
* **Browser APIs:** `window`, `document`, `localStorage`, `navigator`.

### The "Contaminating Children" Problem
If you declare a parent component as a Client Component, **all child components you import within it will automatically become Client Components**. This downloads unnecessary code to the user's browser. Avoid wrapping large layouts in client boundaries.

### The Correct Pattern: Isolate Interactivity

**❌ What you should NOT do (Put "use client" at the very top):**
```tsx
"use client" // ❌ This turns static children into Client Components
import { useState } from 'react'
import HeavyStaticComponent from './HeavyStaticComponent'

export default function ParentPage() {
  const [open, setOpen] = useState(false)
  return (
    <div>
      <button onClick={() => setOpen(!open)}>Open</button>
      <HeavyStaticComponent /> 
    </div>
  )
}
```

**✅ What you SHOULD do (Create a "leaf" component):**
Create a small component just for interactivity and keep the parent on the server.

```tsx
// 1. The Child (Client Component)
"use client"
import { useState } from 'react'

export default function InteractiveButton() {
  const [open, setOpen] = useState(false)
  return <button onClick={() => setOpen(!open)}>Open</button>
}
```

```tsx
// 2. The Parent (Server Component) - Fast, lightweight and WITHOUT "use client"
import InteractiveButton from './InteractiveButton'
import HeavyStaticComponent from './HeavyStaticComponent'

export default function ParentPage() {
  return (
    <div>
      <InteractiveButton /> {/* Only this goes to the browser */}
      <HeavyStaticComponent /> {/* Server rendered */}
    </div>
  )
}
```

### Prop Serialization (Limitation)
**You cannot pass callback functions (e.g. `onClick={() => console.log("hello")}`) from a Server Component to a Client Component** unless it is a Server Action (`"use server"`).
- If you need a callback, declare it directly inside the Client Component.
- If you need parent/child communication, encapsulate both behaviors in the same Client Component or use the URL state.

## Clean Code & VaultLock Rules
- UI must follow the `ui-architecture` skill (Geist fonts, Jade color, Tailwind CSS).
- Types must follow the `typescript-zod` skill (NO `any`, strict interfaces).

From 2004sfm/vaultlock, MIT.

More from 2004sfm/vaultlock