Next.js 15 + App Router 스페셜리스트은(는) 무엇을 하나요?
Quetrex 개발을 위한 완전한 Next.js 15 참고서
이 스킬은 Next.js 15 App Router의 모든 패턴에 대한 포괄적인 지침을 제공하여 에이전트가 최신 Next.js를 처음부터 올바르게 구현하도록 보장합니다.
중요 규칙 (절대 위반 금지)
다음 규칙은 절대 협상 불가입니다. 위반 시 빌드가 실패합니다.
1. 항상 next/image의 <Image> 사용 - <img> 사용 금지
// ✅ 항상 이렇게 하세요
import Image from 'next/image'
<Image src="/logo.png" alt="로고" width={200} height={100} />
<Image src={user.avatar} alt={user.name} width={40} height={40} />
// ❌ 절대 이렇게 하지 마세요 - 빌드 실패
<img src="/logo.png" alt="로고" />
<img src={user.avatar} alt={user.name} />
이유: Next.js Image 컴포넌트는 자동 최적화, 지연 로딩을 제공하고 레이아웃 시프트를 방지합니다. ESLint는 <img> 사용 시 빌드 실패하도록 구성되어 있습니다.
2. 서버 컴포넌트가 기본값 - 필요한 경우에만 'use client' 추가
3. async 클라이언트 컴포넌트는 절대 만들지 않음
4. fetch()에 항상 캐시 전략 지정
이 스킬을 사용해야 하는 경우
다음 작업 시 이 스킬을 사용하세요:
- 새 라우트나 페이지 생성
- 데이터 패칭 구현 (서버 컴포넌트 vs 클라이언트 컴포넌트)
- 서버 vs 클라이언트 컴포넌트 결정
- 서버 액션 및 폼 처리
- 스트리밍 및 Suspense
- 메타데이터 및 SEO
- 라우트 핸들러 (API 라우트)
- 캐싱 전략
- 성능 최적화
전체 문서
이 스킬은 모든 Next.js 15 패턴을 다루는 포괄적인 가이드를 포함합니다:
📁 App Router 완전 가이드
45개 이상의 예제 포함:
- 파일 기반 라우팅 (page.tsx, layout.tsx, route.ts)
- 동적 라우트 ([id], [...slug], [[...slug]])
- 라우트 그룹 ((group))
- 비공개 폴더 (_folder)
- 라우트 핸들러 (API 라우트)
- 레이아웃 및 템플릿
- 로딩 UI (loading.tsx)
- 에러 바운더리 (error.tsx, global-error.tsx)
- 찾을 수 없음 페이지 (not-found.tsx)
- 병렬 라우트 (@folder)
- 인터셉팅 라우트 ((.)folder)
- 라우트 세그먼트 설정 (dynamic, revalidate, runtime)
🔄 데이터 패칭 완전 가이드
35개 이상의 예제 포함:
- 서버 컴포넌트 데이터 패칭 (async/await)
- 클라이언트 컴포넌트 데이터 패칭 (useEffect, React Query, SWR)
- 병렬 데이터 패칭 (Promise.all)
- 순차 데이터 패칭 (워터폴 방지)
- 스트리밍 데이터 (Suspense 바운더리)
- 서버 전송 이벤트 (Quetrex 음성용 SSE)
- 데이터 변경 (서버 액션)
- 낙관적 업데이트 (useOptimistic)
- 폼 처리 (useFormStatus, useActionState)
- 요청 중복 제거
- 데이터 사전 로딩
💾 캐싱 전략 가이드
35개 이상의 예제 포함:
- 요청 메모이제이션 (자동 중복 제거)
- 데이터 캐시 (fetch 캐시 동작)
- 전체 라우트 캐시 (정적 vs 동적)
- 라우터 캐시 (클라이언트 측 캐시)
- 캐시 설정 (force-cache, no-store, revalidate)
- 캐시 태그 (revalidateTag, revalidatePath)
- 온디맨드 재검증
- 시간 기반 재검증 (ISR)
- 캐시 디버깅 기법
- 캐시 옵트아웃
⚡ 서버 액션 완전 가이드
31개 이상의 예제 포함:
- 기본 서버 액션 패턴
- 폼 액션 (점진적 향상)
- 버튼 액션 (프로그래매틱 호출)
- useFormStatus 훅 (로딩 상태)
- useActionState 훅 (상태 관리)
- useOptimistic 훅 (낙관적 UI)
- 액션 내 에러 처리
- Zod를 사용한 검증
- JSON 반환 vs 리디렉트
- 보안 (인증, CSRF)
- 속도 제한
- 데이터베이스 트랜잭션
🎯 메타데이터 API 가이드
26개 이상의 예제 포함:
- 정적 메타데이터 (내보낸 객체)
- 동적 메타데이터 (generateMetadata)
- 파일 기반 메타데이터 (icon.png, opengraph-image.png)
- Open Graph 메타데이터
- Twitter 카드
- JSON-LD 구조화된 데이터
- Viewport 설정
- PWA 매니페스트
- Robots.txt
- 사이트맵 생성
✅ 패턴 검증기
실행 가능한 Python 스크립트로 다음을 검사:
- 서버 컴포넌트가 클라이언트 전용 API를 사용하지 않는지
- 클라이언트 컴포넌트에 'use client' 지시문이 있는지
- 데이터 패칭이 적절한 캐시 전략을 사용하는지
- 서버 액션이 'use server'로 표시되었는지
- 메타데이터 API가 올바르게 사용되었는지
- 이미지 최적화 ( 사용, 미사용)
- 무거운 컴포넌트에 동적 임포트 사용
실행: python validate-patterns.py /path/to/src
빠른 참조
서버 vs 클라이언트 컴포넌트 결정 트리
상호작용이 필요합니까? (onClick, onChange 등)
├─ 예 → 클라이언트 컴포넌트 ('use client')
└─ 아니오 → 서버 컴포넌트 (기본값)
React 훅이 필요합니까? (useState, useEffect)
├─ 예 → 클라이언트 컴포넌트
└─ 아니오 → 서버 컴포넌트
브라우저 API가 필요합니까? (window, localStorage)
├─ 예 → 클라이언트 컴포넌트
└─ 아니오 → 서버 컴포넌트
데이터를 패칭해야 합니까?
├─ 서버 컴포넌트 사용 (권장)
└─ 데이터가 반드시 클라이언트 측에 있어야 하는 경우에만 클라이언트 컴포넌트 사용
컴포넌트가 순수 프레젠테이션용입니까?
└─ 서버 컴포넌트 (더 나은 성능)
일반 패턴
1. 서버 컴포넌트 데이터 패칭
// app/projects/page.tsx
export default async function ProjectsPage() {
const projects = await db.project.findMany()
return <ProjectList projects={projects} />
}
2. 상호작용이 있는 클라이언트 컴포넌트
// components/ProjectCard.tsx
'use client'
import { useState } from 'react'
export function ProjectCard({ project }: Props) {
const [loading, setLoading] = useState(false)
const handleDelete = async () => {
setLoading(true)
await deleteProject(project.id)
setLoading(false)
}
return (
<div>
<h2>{project.name}</h2>
<button onClick={handleDelete} disabled={loading}>
삭제
</button>
</div>
)
}
3. 폼을 사용한 서버 액션
// app/actions.ts
'use server'
export async function createProject(formData: FormData) {
const name = formData.get('name') as string
const project = await db.project.create({ data: { name } })
revalidatePath('/projects')
return { success: true, project }
}
// app/projects/new/page.tsx
import { createProject } from '@/app/actions'
export default function NewProjectPage() {
return (
<form action={createProject}>
<input name="name" required />
<button type="submit">생성</button>
</form>
)
}
4. Suspense를 사용한 스트리밍
// app/dashboard/page.tsx
import { Suspense } from 'react'
export default function DashboardPage() {
return (
<div>
<Suspense fallback={<ProjectsSkeleton />}>
<ProjectsAsync />
</Suspense>
<Suspense fallback={<UsersSkeleton />}>
<UsersAsync />
</Suspense>
</div>
)
}
async function ProjectsAsync() {
const projects = await fetchProjects() // 느린 쿼리
return <ProjectList projects={projects} />
}
5. 동적 메타데이터
// app/blog/[slug]/page.tsx
import type { Metadata } from 'next'
export async function generateMetadata({
params,
}: {
params: Promise<{ slug: string }>
}): Promise<Metadata> {
const { slug } = await params
const post = await fetchPost(slug)
return {
title: post.title,
description: post.excerpt,
openGraph: {
title: post.title,
description: post.excerpt,
images: [post.coverImage],
},
}
}
Quetrex를 위한 모범 사례
1. 서버 컴포넌트를 기본으로
// ✅ 올바름: 서버 컴포넌트 (기본값)
export default async function ProjectsPage() {
const projects = await fetchProjects()
return <ProjectList projects={projects} />
}
// ❌ 틀림: 필요하지 않은데 클라이언트 컴포넌트 사용
'use client'
export default function ProjectsPage() {
const [projects, setProjects] = useState([])
useEffect(() => {
fetchProjects().then(setProjects)
}, [])
return <ProjectList projects={projects} />
}
2. 적절한 캐시 전략 사용
// 정적 콘텐츠 (영구 캐시)
const categories = await fetch('https://api.example.com/categories', {
cache: 'force-cache',
}).then(r => r.json())
// 동적 콘텐츠 (캐시 없음)
const user = await fetch('https://api.example.com/me', {
cache: 'no-store',
}).then(r => r.json())
// ISR (1시간마다 재검증)
const products = await fetch('https://api.example.com/products', {
next: { revalidate: 3600 },
}).then(r => r.json())
3. 적절한 에러 바운더리 구현
// app/dashboard/error.tsx
'use client'
export default function DashboardError({
error,
reset,
}: {
error: Error
reset: () => void
}) {
return (
<div>
<h2>문제가 발생했습니다!</h2>
<button onClick={reset}>다시 시도</button>
</div>
)
}
4. 로딩 상태 사용
// app/dashboard/loading.tsx
export default function DashboardLoading() {
return <DashboardSkeleton />
}
5. 이미지 최적화
// ✅ 올바름: next/image 사용
import Image from 'next/image'
export function ProjectCard({ project }) {
return (
<Image
src={project.image}
alt={project.name}
width={400}
height={300}
/>
)
}
// ❌ 틀림: <img> 태그 사용
export function ProjectCard({ project }) {
return <img src={project.image} alt={project.name} />
}
피해야 할 일반적인 실수
❌ 실수 1: async 클라이언트 컴포넌트
// ❌ 틀림: 문법 오류
'use client'
export default async function BadComponent() {
const data = await fetch('/api/data')
return <div>{data}</div>
}
// ✅ 올바름: 서버 컴포넌트 또는 useEffect 사용
export default async function GoodComponent() {
const data = await fetch('/api/data')
return <div>{data}</div>
}
❌ 실수 2: 서버 컴포넌트에서 클라이언트 API 사용
// ❌ 틀림: 서버 컴포넌트는 브라우저 API를 사용할 수 없음
export default function BadComponent() {
const [state, setState] = useState(false) // 오류!
return <div>{state}</div>
}
// ✅ 올바름: 'use client' 지시문 추가
'use client'
export default function GoodComponent() {
const [state, setState] = useState(false)
return <div>{state}</div>
}
❌ 실수 3: 캐시 전략 누락
// ❌ 틀림: 불명확한 캐싱 동작
const data = await fetch('/api/data')
// ✅ 올바름: 명시적 캐시 전략
const data = await fetch('/api/data', {
cache: 'no-store', // 또는 'force-cache', 또는 { next: { revalidate: 60 } }
})
❌ 실수 4: <Image> 사용 안 함
// ❌ 틀림: 최적화되지 않은 이미지
<img src="/logo.png" alt="로고" />
// ✅ 올바름: Next.js Image 최적화 사용
<Image src="/logo.png" alt="로고" width={200} height={100} />
문제 해결
오류: "useState가 필요한 컴포넌트를 가져오고 있습니다..."
해결책: 컴포넌트 파일에 'use client'를 추가하세요.
오류: "async/await는 클라이언트 컴포넌트에서 유효하지 않습니다"
해결책: 'use client'를 제거하거나 async 컴포넌트 대신 useEffect를 사용하세요.
오류: "process가 정의되지 않았습니다"
해결책: 클라이언트 컴포넌트의 환경 변수는 NEXT_PUBLIC_ 접두사가 필요합니다.
오류: "Headers가 이미 전송되었습니다"
해결책: 응답을 보낸 후에는 headers()나 cookies()를 사용하지 마세요. 스트리밍 전에 호출하세요.
공식 문서
- Next.js 15.5 문서: https://nextjs.org/docs
- App Router: https://nextjs.org/docs/app
- 데이터 패칭: https://nextjs.org/docs/app/building-your-application/data-fetching
- 서버 액션: https://nextjs.org/docs/app/building-your-application/data-fetching/server-actions-and-mutations
- 캐싱: https://nextjs.org/docs/app/building-your-application/caching
- 메타데이터: https://nextjs.org/docs/app/building-your-application/optimizing/metadata
- 예제: https://github.com/vercel/next.js/tree/canary/examples
검증
패턴 검증기를 실행하여 코드를 확인하세요:
python .claude/skills/nextjs-15-specialist/validate-patterns.py src/
검증기는 다음을 확인합니다:
- ✅ async 클라이언트 컴포넌트 (금지)
- ✅ 서버 컴포넌트 내 클라이언트 API
- ✅ 'use client' 지시문 배치
- ✅ 서버 액션 비동기 함수
- ✅ 이미지 최적화
- ✅ 동적 라우트의 메타데이터
- ✅ 무거운 컴포넌트에 대한 동적 임포트
- ✅ fetch 캐시 전략
- ✅ 라우트 세그먼트 설정
요약
이 스킬은 다음을 보장합니다:
- 올바른 컴포넌트 유형 선택 (서버 vs 클라이언트)
- 적절한 데이터 패칭 패턴 구현
- 적절한 캐싱 전략 사용
- 서버 액션 올바르게 처리
- 메타데이터 및 SEO 최적화
- 일반적인 Next.js 실수 방지
- Quetrex 아키텍처 가이드라인 준수
의문이 있을 때:
- 특정 가이드 읽기 (위 링크)
- 검증기 실행
- 공식 Next.js 15 문서 확인
- 서버 컴포넌트를 기본으로 사용
최종 업데이트: 2025-11-23 Next.js 버전: 15.5 총 예제 수: 150개 이상 총 라인 수: 4,000줄 이상
