템플릿 컴포넌트 활용

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

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

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

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

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

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

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

• 공유 layout.tsx는 클라이언트 탐색에서 유지할 헤더·사이드바와 하위 UI를 감쌉니다. 레이아웃의 재사용 자체가 임의의 데이터 함수에 캐시를 만드는 것은 아닙니다.
• template.tsx는 자신의 세그먼트 키가 바뀔 때 새 인스턴스와 DOM을 만들고 내부 클라이언트 상태를 초기화합니다. 이 경계에서 애니메이션이나 로거를 다시 시작할 수 있습니다.

두 파일 모두 기본적으로 서버 컴포넌트이며 children으로 받은 하위 UI를 감쌉니다.

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

다른 경계를 생략한 포함 관계: layout.tsx (루트) -> template.tsx (루트) -> layout.tsx (세그먼트) -> template.tsx (세그먼트) -> page.tsx

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

app/dashboard/template.tsx를 기준으로 이동 범위를 비교하면 다음과 같습니다.

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

템플릿 컴포넌트 구현 실습

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

이 예제에서는 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로 접속합니다.

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

/dashboard/overview, /dashboard/analytics, /dashboard/settings처럼 이 템플릿의 키를 바꾸는 형제 화면으로 이동하면 콘텐츠의 초기 애니메이션이 다시 시작됩니다. 이 동작은 새 마운트 시 initial에서 animate로 전환하도록 작성한 코드에 따른 것입니다.

같은 초기 마운트 애니메이션을 공유 레이아웃에 두면 그 레이아웃을 재사용하는 탐색만으로는 다시 시작하지 않습니다. 상태나 props로 별도 애니메이션을 제어하는 경우와는 구별합니다.

직접 해 보기: 애니메이션보다 상태로 경계 확인하기

짧은 애니메이션을 눈으로 구별하기 어렵다면 다음 카운터를 별도 파일로 만듭니다. useState를 사용하는 작은 Client Component이므로, 바깥 레이아웃 전체를 Client Component로 바꿀 필요는 없습니다.

"use client";

import { useState } from 'react';

export default function ScopeCounter() {
  const [count, setCount] = useState(0);
  return (
    <button type="button" onClick={() => setCount((value) => value + 1)}>
      경계 안의 클릭 수: {count}
    </button>
  );
}

먼저 dashboard/template.tsx에 import ScopeCounter from './ScopeCounter';를 추가하고 기존 motion.div 안의 {children} 앞에 <ScopeCounter />를 넣습니다. 기존 {children}과 애니메이션 코드는 유지합니다. 클릭 수를 올린 뒤 개요 → 분석을 메뉴의 Link로 이동해 새 마운트에서 0부터 시작하는지 확인합니다.

비교하려면 같은 카운터의 배치를 템플릿에서 제거하고 dashboard/layout.tsx의 JSX 안, {children}보다 바깥에 한 번만 둡니다. 해당 레이아웃에도 같은 상대 경로 import를 추가합니다. 두 배치를 동시에 남기지 말고, 같은 공유 레이아웃 아래의 Link 이동에서 상태가 유지되는지 비교합니다. 이 실습의 대상은 브라우저 새로고침이 아닙니다.

스스로 확인하기

카운터가 다시 dashboard/template.tsx 안에 있고, 각 실험 시작 시 클릭 수를 2로 올렸다고 가정합니다. 다음 세 이동에서 이 카운터가 초기화되는지와 그 이유를 설명해 보세요.

1. /dashboard/overview → /dashboard/analytics
2. /dashboard/profile/edit → /dashboard/profile/security
3. /dashboard/overview?tab=a → /dashboard/overview?tab=b

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

• 애니메이션과 초기화 경계: 재마운트가 필요한 화면 범위를 파일 위치로 지정하고, 그 안의 초기 애니메이션·클라이언트 상태·측정 구간을 함께 새로 시작할 수 있습니다.

• 재마운트 비용: DOM 생성과 클라이언트 Effect 설정이 반복됩니다. 비용의 크기는 실제 컴포넌트에서 측정해야 합니다.
• 내부 클라이언트 상태 소실: 유지하려던 폼 입력값이나 선택 상태도 같은 경계 안에 있으면 초기화됩니다.
• 필요한 범위에만 적용: UI 공유만 필요하면 레이아웃으로 충분합니다. 새 인스턴스가 필요한 구간에 템플릿을 둡니다.