템플릿 컴포넌트 활용

Next.js App Router에서 UI를 공유하고 재사용하는 방법으로는 layout.tsx 파일로 정의하는 레이아웃 컴포넌트가 가장 보편적입니다.

하지만 때로는 레이아웃과 유사하게 공통 UI를 제공하면서도, 페이지 이동 시 컴포넌트 인스턴스를 새로 생성하고 상태를 초기화해야 하는 경우가 있습니다.

이때 사용되는 것이 바로 템플릿 컴포넌트(template.tsx)입니다.

이 절에서는 템플릿 컴포넌트가 레이아웃 컴포넌트와 어떻게 다른지, 그리고 어떤 상황에서 템플릿 컴포넌트를 활용해야 하는지 구체적인 예시와 함께 알아보겠습니다.

템플릿 컴포넌트란 무엇인가요?

템플릿 컴포넌트는 app 디렉터리 내의 특정 라우트 세그먼트 폴더 안에 위치한 template.tsx 파일입니다.

레이아웃과 마찬가지로 children prop을 받아 해당 라우트의 콘텐츠를 감싸는 역할을 합니다.

템플릿 컴포넌트는 레이아웃과 페이지 사이에 위치하여, 레이아웃이 자식들을 감싸고, 템플릿이 다시 그 레이아웃의 자식(즉, 페이지)을 감싸는 형태로 작동합니다.

렌더링 순서: layout.tsx (루트) -> template.tsx (루트) -> layout.tsx (세그먼트) -> template.tsx (세그먼트) -> page.tsx

템플릿 컴포넌트 활용 시나리오

먼저 layout.tsx와 template.tsx가 라우트 이동 때 어떻게 다르게 살아남는지 한 장으로 비교해 봅니다.

핵심은 공통 UI 자체가 아니라, 상태를 유지할지 새로 시작할지의 차이입니다.

템플릿 컴포넌트는 다음과 같은 경우에 유용합니다.

템플릿 컴포넌트 구현 실습

간단한 페이지 전환 효과를 통해 템플릿 컴포넌트의 작동 방식을 이해해 봅시다.

이 예제에서는 Framer Motion 라이브러리를 사용하여 페이지 전환 애니메이션을 구현합니다.

npm install framer-motion
# 또는
yarn add framer-motion

"use client"; // 클라이언트 컴포넌트임을 명시

import { motion } from 'framer-motion';

export default function DashboardTemplate({ children }: { children: React.ReactNode }) {
  return (
    // motion.div는 Framer Motion의 애니메이션 가능한 div 컴포넌트입니다.
    <motion.div
      initial={{ opacity: 0, y: 20 }}
      animate={{ opacity: 1, y: 0 }}
      transition={{ duration: 0.5, ease: "easeOut" }}
    >
      {children} {/* 여기에 대시보드 페이지 콘텐츠가 렌더링됩니다 */}
    </motion.div>
  );
}

// ...
export default async function DashboardLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  const userInfo = await getUserInfo(); // 기존 예시 코드 유지
  return (
    <div style={{ display: 'flex', minHeight: 'calc(100vh - 180px)', border: '1px solid #ccc', borderRadius: '8px', overflow: 'hidden' }}>
    {/* ... */}
    </div>
  );
}

실습 확인: 개발 서버(npm run dev)를 실행한 후, http://localhost:3000/dashboard로 접속합니다.

그 다음 대시보드 메뉴의 다른 링크들(예: 개요, 분석, 설정)을 클릭해 보세요.

각 페이지로 이동할 때마다 대시보드 콘텐츠 부분이 아래에서 위로 부드럽게 나타나는 애니메이션 효과를 볼 수 있습니다.

이 애니메이션은 template.tsx가 라우트 변경마다 새로 마운트되면서 initial 상태에서 animate 상태로 전환되기 때문에 발생합니다.

만약 이 애니메이션을 layout.tsx에 직접 적용했다면, 레이아웃은 페이지 이동 시 상태를 유지하므로 애니메이션이 재실행되지 않았을 것입니다.

템플릿 컴포넌트 사용의 장단점

• 페이지 전환 애니메이션 구현 용이: 페이지 이동마다 UI가 새로 마운트되므로 애니메이션 라이브러리와 연동하기 좋습니다.
• 클라이언트 컴포넌트 상태 초기화: 특정 라우트 그룹 내의 페이지 이동 시 클라이언트 컴포넌트의 상태를 강제로 초기화할 수 있습니다.
• 특정 로직의 재실행 보장: 페이지 뷰마다 특정 로거를 초기화하거나 성능 측정을 재설정하는 등, 매번 실행되어야 하는 로직에 유용합니다.

• 성능 오버헤드: 페이지 이동 시 컴포넌트 트리의 일부가 새로 마운트되므로, 레이아웃을 사용하는 것보다는 약간의 성능 오버헤드가 발생할 수 있습니다. 꼭 필요한 경우에만 사용해야 합니다.
• 서버 컴포넌트 상태 유지 불가: 템플릿 자체는 서버 컴포넌트일 수 있지만, 그 안에 클라이언트 컴포넌트가 있다면 해당 클라이언트 컴포넌트의 상태는 페이지 이동 시 초기화됩니다. 이는 장점이자 단점이 될 수 있습니다.
• 남용 금지: 모든 공통 UI에 템플릿을 사용하는 것은 비효율적입니다. 대부분의 공통 UI는 레이아웃 컴포넌트로 충분합니다.

아래 다이어그램처럼 유지해야 할 공통 UI는 layout.tsx에, 이동마다 다시 시작해야 할 동작은 template.tsx에 두면 선택 기준이 명확해집니다.

템플릿은 “공통 UI”라는 이름만 보고 추가하기보다, 탐색마다 정말 새 인스턴스가 필요한지 확인한 뒤 적용하는 편이 안전합니다.

다음 기준처럼 유지할 상태와 초기화할 상태를 나누면 layout.tsx와 template.tsx의 역할이 충돌하지 않습니다.

템플릿 컴포넌트는 Next.js App Router에서 새 마운트가 필요한 페이지 구조에 사용합니다.

레이아웃과의 차이를 먼저 확인한 뒤, 아래 기준처럼 재마운트가 실제로 필요한 경우에만 적용해야 합니다.

template.tsx를 추가하기 전에는 새로 마운트되어야 하는 이유가 분명한지, 반대로 유지되어야 할 상태를 끊고 있지는 않은지 확인해야 합니다.

이 다이어그램은 템플릿 컴포넌트를 Next.js 프로젝트에 넣을 때 결정해야 할 파일 위치와 런타임 경계를 정리합니다.

위치는 layout.tsx와 비슷하지만 의미는 “공통 UI”보다 “재마운트 경계”에 가깝습니다.

app/
  dashboard/

layout.tsx
    유지되는 대시보드 껍데기

template.tsx
  이동마다 새로 마운트

page.tsx
      현재 URL 본문
    settings/

page.tsx

마지막으로 template.tsx가 layout.tsx와 달리 언제 재마운트를 의도하는지 비교합니다.