@kood/claude-code 0.3.5 → 0.3.7

package/templates/nextjs/docs/library/nextjs/index.md

@@ -0,0 +1,291 @@
+# Next.js - Index
+
+> Next.js 15 App Router 핵심 개념
+
+<context>
+@app-router.md
+@server-actions.md
+@route-handlers.md
+@middleware.md
+@caching.md
+</context>
+
+---
+
+## 핵심 개념
+
+| 개념 | 설명 |
+|------|------|
+| **App Router** | 파일 기반 라우팅 (`app/` 디렉토리) |
+| **Server Components** | 기본 컴포넌트 (서버 렌더링) |
+| **Client Components** | `"use client"` 선언 필요 |
+| **Server Actions** | `"use server"` 함수 (타입 안전 API) |
+| **Route Handlers** | REST API 엔드포인트 (`app/api/`) |
+
+---
+
+## 빠른 시작
+
+### 프로젝트 생성
+
+```bash
+npx create-next-app@latest my-app --typescript --tailwind --app
+cd my-app
+npm run dev
+```
+
+### 기본 페이지
+
+```typescript
+// app/page.tsx (Server Component - 기본)
+export default async function HomePage() {
+  const data = await fetch('https://api.example.com/data')
+  const json = await data.json()
+
+  return <div>{json.title}</div>
+}
+```
+
+### Client Component
+
+```typescript
+// app/_components/counter.tsx
+"use client"
+
+import { useState } from "react"
+
+export function Counter() {
+  const [count, setCount] = useState(0)
+  return <button onClick={() => setCount(count + 1)}>{count}</button>
+}
+```
+
+---
+
+## 파일 구조
+
+```
+app/
+├── layout.tsx          # Root layout (필수)
+├── page.tsx            # Home (/)
+├── about/
+│   └── page.tsx        # /about
+├── blog/
+│   ├── page.tsx        # /blog
+│   └── [slug]/
+│       └── page.tsx    # /blog/:slug
+└── api/
+    └── posts/
+        └── route.ts    # API /api/posts
+```
+
+---
+
+## 주요 파일
+
+| 파일 | 용도 |
+|------|------|
+| `layout.tsx` | 공통 레이아웃 (중첩 가능) |
+| `page.tsx` | 페이지 컴포넌트 |
+| `loading.tsx` | 로딩 UI (Suspense) |
+| `error.tsx` | 에러 UI (Error Boundary) |
+| `not-found.tsx` | 404 페이지 |
+| `route.ts` | API 엔드포인트 |
+
+---
+
+## Server vs Client Components
+
+| 구분 | Server | Client |
+|------|--------|--------|
+| 선언 | 기본 | `"use client"` |
+| 데이터 페칭 | ✅ async/await | ❌ (useQuery 사용) |
+| Hooks | ❌ | ✅ useState, useEffect |
+| 브라우저 API | ❌ | ✅ window, localStorage |
+| Event Handlers | ❌ | ✅ onClick, onChange |
+
+**규칙:**
+- Server Component가 기본 → Client Component 필요 시만 `"use client"` 추가
+- Server Component 안에 Client Component 포함 가능
+- Client Component 안에 Server Component 불가 (props로 전달은 가능)
+
+---
+
+## Server Actions
+
+```typescript
+// app/actions.ts
+"use server"
+
+import { z } from "zod"
+import { revalidatePath } from "next/cache"
+
+const schema = z.object({
+  title: z.string().min(1),
+  content: z.string(),
+})
+
+export async function createPost(formData: FormData) {
+  const parsed = schema.parse({
+    title: formData.get("title"),
+    content: formData.get("content"),
+  })
+
+  const post = await prisma.post.create({ data: parsed })
+  revalidatePath("/posts")
+  return post
+}
+```
+
+---
+
+## Route Handlers
+
+```typescript
+// app/api/posts/route.ts
+import { NextRequest, NextResponse } from "next/server"
+
+export async function GET(request: NextRequest) {
+  const posts = await prisma.post.findMany()
+  return NextResponse.json(posts)
+}
+
+export async function POST(request: NextRequest) {
+  const body = await request.json()
+  const post = await prisma.post.create({ data: body })
+  return NextResponse.json(post, { status: 201 })
+}
+```
+
+---
+
+## Middleware
+
+```typescript
+// middleware.ts
+import { NextResponse } from "next/server"
+import type { NextRequest } from "next/server"
+
+export function middleware(request: NextRequest) {
+  const token = request.cookies.get("token")
+
+  if (!token) {
+    return NextResponse.redirect(new URL("/login", request.url))
+  }
+
+  return NextResponse.next()
+}
+
+export const config = {
+  matcher: ["/dashboard/:path*", "/profile/:path*"],
+}
+```
+
+---
+
+## 데이터 페칭
+
+### Server Component (권장)
+
+```typescript
+export default async function PostsPage() {
+  const posts = await prisma.post.findMany() // 직접 DB 접근
+  return <PostsList posts={posts} />
+}
+```
+
+### Client Component (TanStack Query)
+
+```typescript
+"use client"
+
+import { useQuery } from "@tanstack/react-query"
+
+export function PostsList() {
+  const { data } = useQuery({
+    queryKey: ["posts"],
+    queryFn: () => fetch("/api/posts").then(r => r.json()),
+  })
+
+  return <ul>{data?.map(post => <li key={post.id}>{post.title}</li>)}</ul>
+}
+```
+
+---
+
+## 캐싱
+
+| 함수 | 용도 |
+|------|------|
+| `revalidatePath("/posts")` | 특정 경로 캐시 무효화 |
+| `revalidateTag("posts")` | 태그 기반 캐시 무효화 |
+| `unstable_cache()` | 함수 결과 캐싱 |
+
+```typescript
+import { revalidatePath, revalidateTag } from "next/cache"
+
+export async function createPost(data: PostInput) {
+  const post = await prisma.post.create({ data })
+
+  revalidatePath("/posts") // /posts 캐시 무효화
+  revalidateTag("posts")   // "posts" 태그 캐시 무효화
+
+  return post
+}
+```
+
+---
+
+## 환경 변수
+
+```bash
+# .env.local
+DATABASE_URL="postgresql://..."
+NEXTAUTH_SECRET="..."
+NEXTAUTH_URL="http://localhost:3000"
+NEXT_PUBLIC_API_URL="https://api.example.com"
+```
+
+**규칙:**
+- `NEXT_PUBLIC_*`: 클라이언트에서 접근 가능
+- 나머지: 서버 전용
+
+---
+
+## 배포
+
+### Vercel (권장)
+
+```bash
+npm i -g vercel
+vercel
+```
+
+### Docker
+
+```dockerfile
+FROM node:20-alpine
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci
+COPY . .
+RUN npm run build
+CMD ["npm", "start"]
+```
+
+### Node.js
+
+```bash
+npm run build
+npm start
+```
+
+---
+
+## 참조
+
+- [App Router](app-router.md)
+- [Server Actions](server-actions.md)
+- [Route Handlers](route-handlers.md)
+- [Middleware](middleware.md)
+- [Caching](caching.md)

package/templates/nextjs/docs/library/nextjs/middleware.md

@@ -0,0 +1,391 @@
+# Middleware
+
+> 요청 처리 전 실행되는 함수
+
+---
+
+## 기본 사용법
+
+```typescript
+// middleware.ts (루트)
+import { NextResponse } from "next/server"
+import type { NextRequest } from "next/server"
+
+export function middleware(request: NextRequest) {
+  // 로직 실행...
+  return NextResponse.next()
+}
+
+// 매처 설정
+export const config = {
+  matcher: ["/dashboard/:path*", "/api/:path*"],
+}
+```
+
+---
+
+## Response 타입
+
+### NextResponse.next()
+
+```typescript
+// 요청을 다음 미들웨어 또는 라우트로 전달
+export function middleware(request: NextRequest) {
+  return NextResponse.next()
+}
+```
+
+### NextResponse.redirect()
+
+```typescript
+// 다른 URL로 리다이렉트
+export function middleware(request: NextRequest) {
+  return NextResponse.redirect(new URL("/login", request.url))
+}
+```
+
+### NextResponse.rewrite()
+
+```typescript
+// URL은 유지하되 다른 페이지 렌더링
+export function middleware(request: NextRequest) {
+  return NextResponse.rewrite(new URL("/dashboard/home", request.url))
+}
+```
+
+---
+
+## 인증
+
+```typescript
+import { NextResponse } from "next/server"
+import type { NextRequest } from "next/server"
+
+export function middleware(request: NextRequest) {
+  const token = request.cookies.get("token")
+
+  // 토큰 없으면 로그인 페이지로
+  if (!token) {
+    return NextResponse.redirect(new URL("/login", request.url))
+  }
+
+  return NextResponse.next()
+}
+
+export const config = {
+  matcher: ["/dashboard/:path*", "/profile/:path*"],
+}
+```
+
+---
+
+## 쿠키 처리
+
+### 읽기
+
+```typescript
+export function middleware(request: NextRequest) {
+  const token = request.cookies.get("token")
+  const userId = request.cookies.get("userId")
+
+  console.log({ token, userId })
+
+  return NextResponse.next()
+}
+```
+
+### 설정
+
+```typescript
+export function middleware(request: NextRequest) {
+  const response = NextResponse.next()
+
+  response.cookies.set("visited", "true", {
+    httpOnly: true,
+    secure: true,
+    maxAge: 60 * 60 * 24 * 7, // 7일
+  })
+
+  return response
+}
+```
+
+---
+
+## Headers 처리
+
+### 읽기
+
+```typescript
+export function middleware(request: NextRequest) {
+  const userAgent = request.headers.get("user-agent")
+  const authorization = request.headers.get("authorization")
+
+  console.log({ userAgent, authorization })
+
+  return NextResponse.next()
+}
+```
+
+### 설정
+
+```typescript
+export function middleware(request: NextRequest) {
+  const response = NextResponse.next()
+
+  response.headers.set("X-Custom-Header", "value")
+  response.headers.set("X-Request-Id", crypto.randomUUID())
+
+  return response
+}
+```
+
+---
+
+## 경로별 처리
+
+```typescript
+export function middleware(request: NextRequest) {
+  const { pathname } = request.nextUrl
+
+  // /api/* 경로
+  if (pathname.startsWith("/api/")) {
+    const token = request.headers.get("authorization")
+
+    if (!token) {
+      return NextResponse.json({ error: "Unauthorized" }, { status: 401 })
+    }
+  }
+
+  // /admin/* 경로
+  if (pathname.startsWith("/admin/")) {
+    const role = request.cookies.get("role")?.value
+
+    if (role !== "admin") {
+      return NextResponse.redirect(new URL("/", request.url))
+    }
+  }
+
+  return NextResponse.next()
+}
+```
+
+---
+
+## Matcher 설정
+
+### 배열
+
+```typescript
+export const config = {
+  matcher: ["/dashboard/:path*", "/profile/:path*"],
+}
+```
+
+### 정규식
+
+```typescript
+export const config = {
+  matcher: [
+    /*
+     * 다음 경로 제외:
+     * - _next/static (정적 파일)
+     * - _next/image (이미지 최적화)
+     * - favicon.ico (파비콘)
+     */
+    "/((?!_next/static|_next/image|favicon.ico).*)",
+  ],
+}
+```
+
+### 조건부
+
+```typescript
+export const config = {
+  matcher: [
+    "/dashboard/:path*",
+    {
+      source: "/api/:path*",
+      has: [
+        { type: "header", key: "authorization" },
+      ],
+    },
+  ],
+}
+```
+
+---
+
+## 로깅
+
+```typescript
+export function middleware(request: NextRequest) {
+  const start = Date.now()
+
+  const response = NextResponse.next()
+
+  const duration = Date.now() - start
+
+  console.log({
+    method: request.method,
+    url: request.url,
+    duration: `${duration}ms`,
+    status: response.status,
+  })
+
+  return response
+}
+```
+
+---
+
+## Rate Limiting
+
+```typescript
+import { NextResponse } from "next/server"
+import type { NextRequest } from "next/server"
+
+const rateLimit = new Map<string, { count: number; resetAt: number }>()
+
+const LIMIT = 10 // 10 requests
+const WINDOW = 60 * 1000 // 1분
+
+export function middleware(request: NextRequest) {
+  const ip = request.ip || "unknown"
+  const now = Date.now()
+
+  const record = rateLimit.get(ip)
+
+  if (!record || now > record.resetAt) {
+    rateLimit.set(ip, { count: 1, resetAt: now + WINDOW })
+    return NextResponse.next()
+  }
+
+  if (record.count >= LIMIT) {
+    return NextResponse.json(
+      { error: "Too many requests" },
+      { status: 429 }
+    )
+  }
+
+  record.count++
+  return NextResponse.next()
+}
+
+export const config = {
+  matcher: "/api/:path*",
+}
+```
+
+---
+
+## Geolocation
+
+```typescript
+export function middleware(request: NextRequest) {
+  const country = request.geo?.country || "US"
+  const city = request.geo?.city || "Unknown"
+
+  const response = NextResponse.next()
+  response.headers.set("X-Country", country)
+  response.headers.set("X-City", city)
+
+  return response
+}
+```
+
+---
+
+## A/B 테스팅
+
+```typescript
+import { NextResponse } from "next/server"
+import type { NextRequest } from "next/server"
+
+export function middleware(request: NextRequest) {
+  const bucket = request.cookies.get("bucket")
+
+  if (!bucket) {
+    const newBucket = Math.random() > 0.5 ? "A" : "B"
+    const response = NextResponse.next()
+
+    response.cookies.set("bucket", newBucket)
+
+    if (newBucket === "B") {
+      return NextResponse.rewrite(new URL("/variant-b", request.url))
+    }
+
+    return response
+  }
+
+  if (bucket.value === "B") {
+    return NextResponse.rewrite(new URL("/variant-b", request.url))
+  }
+
+  return NextResponse.next()
+}
+
+export const config = {
+  matcher: "/",
+}
+```
+
+---
+
+## 베스트 프랙티스
+
+### ✅ DO
+
+```typescript
+// 1. 가벼운 로직만
+export function middleware(request: NextRequest) {
+  const token = request.cookies.get("token")
+
+  if (!token) {
+    return NextResponse.redirect(new URL("/login", request.url))
+  }
+
+  return NextResponse.next()
+}
+
+// 2. matcher 설정
+export const config = {
+  matcher: ["/dashboard/:path*"],
+}
+```
+
+### ❌ DON'T
+
+```typescript
+// 1. 무거운 DB 쿼리
+export async function middleware(request: NextRequest) {
+  // ❌ 미들웨어에서 DB 쿼리 금지
+  const user = await prisma.user.findUnique({ where: { id: "..." } })
+  return NextResponse.next()
+}
+
+// 2. matcher 없이 모든 요청 처리
+export function middleware(request: NextRequest) {
+  // ❌ 성능 저하
+  return NextResponse.next()
+}
+```
+
+---
+
+## NextAuth.js와 함께 사용
+
+```typescript
+// middleware.ts
+export { default } from "next-auth/middleware"
+
+export const config = {
+  matcher: ["/dashboard/:path*", "/profile/:path*"],
+}
+```
+
+---
+
+## 참조
+
+- [Next.js Middleware](https://nextjs.org/docs/app/building-your-application/routing/middleware)