Next.js App Router Expert은(는) 무엇을 하나요?
개요
Next.js App Router 개발을 위한 전문 가이드: 페이지 생성, 동적 라우팅, 중첩 레이아웃, 서버/클라이언트 컴포넌트 최적화 및 ERP 역할 기반 대시보드 구축을 다룹니다.
핵심 기능
1. 페이지 생성 (/app/.../page.tsx)
규칙:
- 기본적으로 서버 컴포넌트 사용 (
'use client'지시어 없음) fetch()또는 ORM 쿼리를 사용한 비동기 데이터 페칭- 초기 데이터 로드에
useEffect사용 금지 - 로딩 상태에
Suspense경계 사용 generateMetadata()를 통한 SEO 메타데이터
템플릿:
// app/dashboard/page.tsx
import { Suspense } from 'react';
import { TaskList } from '@/components/TaskList';
import { TaskListSkeleton } from '@/components/TaskListSkeleton';
export const metadata = {
title: '대시보드',
description: '할 일 관리 대시보드',
};
export default async function DashboardPage() {
const tasks = await fetchTasks();
return (
<main className="p-4">
<h1>대시보드</h1>
<Suspense fallback={<TaskListSkeleton />}>
<TaskList initialTasks={tasks} />
</Suspense>
</main>
);
}
2. 동적 라우트 ([slug]/page.tsx)
사용 시점:
- 학생 프로필:
app/students/[studentId]/page.tsx - 할 일 상세:
app/tasks/[taskId]/page.tsx - 강좌 페이지:
app/courses/[courseId]/page.tsx
규칙:
paramsprop에서 파라미터 추출 (읽기 전용)- SEO를 위해
generateMetadata()사용 not-found.tsx로 404 처리
템플릿:
// app/students/[studentId]/page.tsx
import { notFound } from 'next/navigation';
type Params = Promise<{ studentId: string }>;
export async function generateMetadata({ params }: { params: Params }) {
const { studentId } = await params;
const student = await getStudent(studentId);
if (!student) return { title: '학생을 찾을 수 없음' };
return {
title: `${student.name} - 학생 프로필`,
};
}
export default async function StudentProfile({ params }: { params: Params }) {
const { studentId } = await params;
const student = await getStudent(studentId);
if (!student) notFound();
return <StudentProfileView student={student} />;
}
3. 병렬 라우트 (@folder)
사용 시점:
- 대시보드 변형:
app/dashboard@(admin|teacher)/page.tsx - 분할 레이아웃:
app/settings@(user|organization)/layout.tsx
템플릿:
// app/dashboard/@admin/page.tsx - 관리자 대시보드
export default function AdminDashboard() {
return <AdminPanel />;
}
// app/dashboard/@teacher/page.tsx - 교사 대시보드
export default function TeacherDashboard() {
return <TeacherPanel />;
}
4. 레이아웃과 템플릿
루트 레이아웃 (app/layout.tsx):
import { Providers } from '@/components/Providers';
import './globals.css';
export const metadata = {
title: 'Todo Evolution',
description: '교육을 위한 할 일 관리',
};
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="ko">
<body>
<Providers>{children}</Providers>
</body>
</html>
);
}
중첩 레이아웃 (app/dashboard/layout.tsx):
import { DashboardNav } from '@/components/DashboardNav';
export default function DashboardLayout({
children,
}: {
children: React.ReactNode;
}) {
return (
<div className="flex min-h-screen">
<DashboardNav />
<main className="flex-1 p-6">{children}</main>
</div>
);
}
템플릿 (app/tasks/template.tsx):
// 탐색 시 다시 실행, 폼 상태 유지
export default function TasksTemplate({ children }: { children: React.ReactNode }) {
return (
<div className="bg-gray-50 min-h-screen">
<header className="bg-white shadow">
<h1>할 일 목록</h1>
</header>
{children}
</div>
);
}
5. 서버 vs 클라이언트 컴포넌트
서버 컴포넌트 사용:
- 데이터 페칭
- 직접 데이터베이스 쿼리
- 정적 콘텐츠
- 서버 전용 작업
클라이언트 컴포넌트 ('use client') 사용:
- 브라우저 API (
window,localStorage) - 이벤트 핸들러 (
onClick,onSubmit) - React 훅 (
useState,useEffect) - 상태 관리 (Zustand, Redux)
- 상호작용
// 서버 컴포넌트 (기본값)
export default async function TaskList() {
const tasks = await fetchTasks(); // 직접 DB 쿼리
return <div>{tasks.map(/* ... */)}</div>;
}
// 클라이언트 컴포넌트
'use client';
import { useTaskStore } from '@/store/tasks';
export function TaskFilter() {
const { filter, setFilter } = useTaskStore();
return <button onClick={() => setFilter('all')}>모든 할 일</button>;
}
6. ERP 역할 기반 페이지
역할 가드:
// app/admin/page.tsx
import { requireRole } from '@/lib/auth';
import { redirect } from 'next/navigation';
export default async function AdminPage() {
const session = await getSession();
if (session?.role !== 'admin') {
redirect('/unauthorized');
}
return <AdminDashboard />;
}
KPI 대시보드 (Recharts):
'use client';
import { BarChart, Bar, XAxis, YAxis, Tooltip } from 'recharts';
export function TaskKPIChart({ data }: { data: TaskStats[] }) {
return (
<BarChart width={600} height={300} data={data}>
<XAxis dataKey="date" />
<YAxis />
<Tooltip />
<Bar dataKey="completed" fill="#22c55e" />
</BarChart>
);
}
7. 오류 및 로딩 상태
오류 바운더리 (error.tsx):
'use client';
export default function Error({
error,
reset,
}: {
error: Error & { digest?: string };
reset: () => void;
}) {
return (
<div>
<h2>문제가 발생했습니다!</h2>
<button onClick={reset}>다시 시도</button>
</div>
);
}
로딩 상태 (loading.tsx):
export default function Loading() {
return <div className="animate-pulse">로딩 중...</div>;
}
// 또는 Suspense 사용:
export default async function Page() {
return (
<Suspense fallback={<Loading />}>
<Content />
</Suspense>
);
}
8. shadcn/ui 통합
설치:
npx shadcn@latest add button card input dialog
서버 컴포넌트에서 사용:
import { Button } from '@/components/ui/button';
import { Card, CardContent, CardHeader } from '@/components/ui/card';
export default async function TaskPage() {
const tasks = await getTasks();
return (
<Card>
<CardHeader>할 일</CardHeader>
<CardContent>
{tasks.map(task => (
<div key={task.id}>{task.title}</div>
))}
</CardContent>
</Card>
);
}
워크플로우 결정 트리
사용자 요청 → 분석 → 구현 경로
-
"대시보드/관리자 페이지 만들어 줘" →
page.tsx를 사용한 서버 컴포넌트 → 비동기 데이터 페칭 → 탐색이 필요하면layout.tsx추가 -
"동적 학생 프로필" →
[studentId]/page.tsx생성 → 파라미터 추출 →generateMetadata()추가 → 필요한 경우not-found.tsx생성 -
"공유 레이아웃 추가해 줘" → 대상 폴더에
layout.tsx생성 → 필요한 경우 프로바이더로 감싸기 → children 렌더링 유지 -
"폼 추가해 줘" →
'use client'컴포넌트 → 폼 데이터에 useState 사용 → 제출을 위한 서버 액션 또는 API 라우트 -
"KPI 차트/분석" → Recharts를 위한
'use client'→ 데이터 페치를 포함한 서버 컴포넌트 부모 → 데이터를 props로 전달
품질 체크리스트
작업 완료 표시 전 확인:
- TypeScript strict mode 활성화
- 기본적으로 서버 컴포넌트 사용
- 필요한 경우에만
'use client' - SEO를 위한
generateMetadata() - 비동기 데이터를 위한 Suspense 경계
- 필요한 곳에 오류 바운더리 (
error.tsx) - 수화 불일치 없음
- 성능 최적화 (렌더링 차단 없음)
- 모바일 우선 반응형 디자인
- 접근성 (ARIA 레이블, 키보드 탐색)
공통 패턴
패턴 1: 서버 컴포넌트 + 클라이언트 컴포넌트 혼합
// 서버 컴포넌트
export default async function Page() {
const tasks = await fetchTasks();
return <TaskList tasks={tasks} />; // 상호작용을 위한 클라이언트 컴포넌트
}
'use client';
function TaskList({ tasks }: { tasks: Task[] }) {
const [filter, setFilter] = useState('all');
const filtered = tasks.filter(/* ... */);
return <div>{filtered.map(/* ... */)}</div>;
}
패턴 2: 조직을 위한 라우트 그룹
app/
(marketing)/ # 그룹: URL 세그먼트 없음
about/page.tsx
contact/page.tsx
(dashboard)/ # 그룹: URL 세그먼트 없음
layout.tsx
page.tsx
패턴 3: API 라우트 (라우트 핸들러)
// app/api/tasks/route.ts
import { NextResponse } from 'next/server';
export async function GET() {
const tasks = await db.query.tasks.findMany();
return NextResponse.json(tasks);
}
export async function POST(request: Request) {
const body = await request.json();
const task = await createTask(body);
return NextResponse.json(task, { status: 201 });
}
트리거 예시
- "대시보드 페이지 만들어 줘" → 서버 컴포넌트로
app/dashboard/page.tsx생성 - "동적 학생 프로필 라우트" →
app/students/[studentId]/page.tsx(params, metadata 포함) - "공유 레이아웃 추가해 줘" →
app/dashboard/layout.tsx(children 포함) - "관리자 패널 차트 포함" → 서버 컴포넌트 + 클라이언트 차트 컴포넌트
- "로그인 페이지 만들어 줘" →
'use client'폼 컴포넌트 + API 라우트 - "404 페이지 커스터마이즈" →
app/not-found.tsx - "오류 처리해 줘" →
app/dashboard/error.tsx
참고 자료
고급 패턴은 references/app-router-patterns.md를, 라우트 핸들러 예제는 references/api-routes.md를 참조하세요.