Next.js 16 애플리케이션
올바른 패턴과 독특한 디자인으로 Next.js 16 애플리케이션을 구축합니다.
중요한 비호환 변경 사항 (Next.js 16)
1. params와 searchParams가 이제 Promise
이것은 가장 흔한 실수입니다.
// 잘못된 예 - Next.js 15 패턴 (실패함)
export default function Page({ params }: { params: { id: string } }) {
return <div>ID: {params.id}</div>
}
// 올바른 예 - Next.js 16 패턴
export default async function Page({
params,
}: {
params: Promise<{ id: string }>
}) {
const { id } = await params
return <div>ID: {id}</div>
}
2. 클라이언트 컴포넌트는 use() 훅 필요
"use client"
import { use } from "react"
export default function ClientPage({
params,
}: {
params: Promise<{ id: string }>
}) {
const { id } = use(params)
return <div>ID: {id}</div>
}
3. searchParams도 비동기
export default async function Page({
searchParams,
}: {
searchParams: Promise<{ page?: string }>
}) {
const { page } = await searchParams
return <div>Page: {page ?? "1"}</div>
}
핵심 패턴
프로젝트 설정
npx create-next-app@latest my-app --typescript --tailwind --eslint
cd my-app
# shadcn/ui 추가
npx shadcn@latest init
npx shadcn@latest add button form dialog table sidebar
App Router 레이아웃
// app/layout.tsx
export default function RootLayout({
children,
}: {
children: React.ReactNode
}) {
return (
<html lang="en">
<body className="min-h-screen">
{children}
</body>
</html>
)
}
동적 라우트
// app/tasks/[id]/page.tsx
export default async function TaskPage({
params,
}: {
params: Promise<{ id: string }>
}) {
const { id } = await params
const task = await getTask(id)
return (
<main>
<h1>{task.title}</h1>
</main>
)
}
서버 액션
// app/actions.ts
"use server"
import { revalidatePath } from "next/cache"
export async function createTask(formData: FormData) {
const title = formData.get("title") as string
await db.insert(tasks).values({ title })
revalidatePath("/tasks")
}
// 컴포넌트에서 사용
<form action={createTask}>
<input name="title" />
<button type="submit">Create</button>
</form>
API 라우트
// app/api/tasks/route.ts
import { NextResponse } from "next/server"
export async function GET() {
const tasks = await db.select().from(tasksTable)
return NextResponse.json(tasks)
}
export async function POST(request: Request) {
const body = await request.json()
const task = await db.insert(tasksTable).values(body).returning()
return NextResponse.json(task, { status: 201 })
}
미들웨어 → proxy.ts
// proxy.ts (Next.js 16에서 middleware.ts를 대체)
import { NextRequest } from "next/server"
export function proxy(request: NextRequest) {
// 인증 확인
const token = request.cookies.get("token")
if (!token && request.nextUrl.pathname.startsWith("/dashboard")) {
return Response.redirect(new URL("/login", request.url))
}
}
export const config = {
matcher: ["/dashboard/:path*"],
}
데이터 가져오기
서버 컴포넌트 (기본)
// 서버에서 실행됨 - async/await 직접 사용 가능
async function TaskList() {
const tasks = await fetch("https://api.example.com/tasks", {
cache: "no-store", // SSR, 또는
// next: { revalidate: 60 } // ISR
}).then(r => r.json())
return (
<ul>
{tasks.map(task => <li key={task.id}>{task.title}</li>)}
</ul>
)
}
클라이언트 컴포넌트
"use client"
import useSWR from "swr"
const fetcher = (url: string) => fetch(url).then(r => r.json())
export function ClientTaskList() {
const { data, error, isLoading } = useSWR("/api/tasks", fetcher)
if (isLoading) return <div>Loading...</div>
if (error) return <div>Error loading tasks</div>
return (
<ul>
{data.map(task => <li key={task.id}>{task.title}</li>)}
</ul>
)
}
프로젝트 구조
app/
├── layout.tsx # 루트 레이아웃
├── page.tsx # 홈 페이지
├── globals.css # 전역 스타일
├── api/ # API 라우트
│ └── tasks/route.ts
├── tasks/
│ ├── page.tsx # /tasks
│ └── [id]/page.tsx # /tasks/:id
├── actions.ts # 서버 액션
└── proxy.ts # 요청 프록시 (미들웨어)
components/
├── ui/ # shadcn/ui 컴포넌트
└── task-list.tsx # 앱 컴포넌트
lib/
├── db.ts # 데이터베이스 연결
└── utils.ts # 유틸리티
Next.js DevTools MCP
런타임 진단 및 개발 자동화를 위해 next-devtools-mcp 서버를 사용하세요.
설정
claude mcp add next-devtools npx next-devtools-mcp@latest
또는 settings.json 파일:
{
"mcpServers": {
"next-devtools": {
"type": "stdio",
"command": "npx",
"args": ["next-devtools-mcp@latest"]
}
}
}
사용 가능한 도구
| 도구 | 목적 |
|---|---|
init | 사용 가능한 도구 및 모범 사례에 대한 컨텍스트 설정 |
nextjs_docs | 공식 Next.js 문서 검색 및 가져오기 |
browser_eval | Playwright로 브라우저 테스트 자동화 |
nextjs_index | 실행 중인 Next.js 개발 서버 검색 |
nextjs_call | 실행 중인 개발 서버에서 MCP 도구 실행 |
upgrade_nextjs_16 | Codemod를 통한 자동 업그레이드 |
enable_cache_components | Next.js 16용 Cache Components 구성 |
주요 사용 사례
1. 실시간 오류 확인
"내 Next.js 앱에 어떤 빌드 오류가 있나요?"
"현재 프로젝트의 TypeScript 오류를 보여주세요"
2. 런타임 문제 디버깅
"개발 서버 로그에서 오류를 확인하세요"
"대시보드 페이지에서 어떤 런타임 오류가 발생하나요?"
3. 업그레이드 지원
"이 프로젝트를 Next.js 16으로 업그레이드하세요"
"이 앱에 캐시 컴포넌트를 활성화하세요"
4. 문서 검색
"Next.js 16에서 Image 컴포넌트를 어떻게 사용하나요?"
"동적 라우트를 처리하는 올바른 방법은 무엇인가요?"
Next.js 16 MCP 엔드포인트
Next.js 16+는 http://localhost:3000/_next/mcp (또는 개발 서버 포트)에 내장 MCP 엔드포인트를 노출합니다. devtools MCP는 실행 중인 서버를 자동으로 검색하고 연결합니다.
검증
실행: python3 scripts/verify.py
예상 결과: ✓ building-nextjs-apps skill ready
검증 실패 시
- 확인: references/ 폴더에 nextjs-16-patterns.md 파일이 있는지 확인하세요
- 계속 실패하면 중단하고 보고하세요
관련 스킬
- styling-with-shadcn - Next.js 앱용 UI 컴포넌트
- fetching-library-docs - 최신 Next.js 문서:
--library-id /vercel/next.js --topic routing - configuring-better-auth - Next.js 앱용 OAuth/SSO
참고 자료
- references/nextjs-16-patterns.md - 전체 Next.js 16 패턴
- references/frontend-design.md - 독특한 UI를 위한 미학 지침
- references/datetime-patterns.md - datetime-local 입력을 위한 UTC/시간대 처리