📁 Next.js 2장: App Router 해부학 (파일 시스템 라우팅)

📋 목차

• 📌 이 문서를 읽기 전에
• 🤔 왜 알아야 하는가
• 🏗️ 비유로 먼저 이해하기
• 📄 page.tsx와 layout.tsx의 공생 관계 🟢
• 🧩 layout.tsx vs template.tsx — 무엇이 다를까? 🟡
• 🔀 layout.tsx + template.tsx 함께 쓰면? 🟡
• 🎭 라우트 그룹 (folder)의 마법 🟡
• 🧪 따라해보기: 렌더링 유지 확인하기
• 💥 에러 해결 카탈로그
• 🏁 이번에 배운 내용 총정리
• 📝 마무리 퀴즈
• 🐣 영철이의 퇴근 일기
• 🔗 더 알아보기

📌 이 문서를 읽기 전에

⏱️ 예상 읽기 시간: 15분(전체) / 핵심 파트만: 8분

🗺️ 이 문서의 흐름
파일 기반 라우팅의 원리 → Layout 과 Template 의 차이 → Route Group → 실전 실습 ( 영수네 커뮤니티 예제 )

🎯 이 문서를 다 읽으면 할 수 있는 것

• layout.tsx 와 template.tsx 를 상황에 맞게 골라서 쓸 수 있다.
• 상태(State) 가 유지되어야 하는 UI 와 새로 갱신되는 UI 를 폴더 구조로 분리 설계할 수 있다.
• 라우트 그룹을 활용해 복잡한 대시보드와 유저 페이지의 레이아웃을 우아하게 고립시킬 수 있다.

🗺️ 이 문서의 배경 세계관: '영수네 커뮤니티'

• 🐣 영철 ( 신입 ): "리드 님! 스터디 카테고리 탭을 누를 때마다 화면이 덜컹거리면서, 힘들게 검색해둔 사이드바 필터값이 자꾸 초기화돼요! 유입 경로가 바뀌면 컴포넌트가 다 중단되는 건가요?"
• 🦁 영호 ( 리드 ): "영철 님, 그건 변하지 않는 배경(Layout) 과 변하는 주인공(Page) 을 한 파일에 한 파일에 함께 두어서 그래요. 리액트 라우터 시절의 관습을 아직 못 버리셨군요."
• 👔 영수 ( PM ): "영철 씨, 필터가 매번 초기화되면 유저들이 스터디 찾다가 화나서 앱 지울걸요? 이거 비즈니스적으로 치명적입니다."
• 🎨 영숙 ( UX ): "맞아요. 그리고 탭을 넘길 때마다 화면이 슈웅~ 예쁘게 나타나면 좋겠는데, layout 은 절대로 다시 안 그려진다면서요? 제 애니메이션은 어쩌죠?"
• 🦁 영호 ( 리드 ): "자, 다들 주목! 그래서 우리에겐 Layout 과 Template, 그리고 Route Group 이라는 도구가 있는 겁니다. 오늘 이 대상들의 해부학을 제대로 파헤쳐 보죠."

🤔 왜 알아야 하는가

영수네 커뮤니티("개발자 스터디 매칭 앱") 프로젝트 상황이야.

영철(새로 온 주니어) 이가 스터디 찾기 페이지(/studies) 에서 네비게이션 탭(프론트엔드 모집, 백엔드 모집) 을 누를 때마다 화면 전체가 깜빡이면서 사이드바 필터까지 초기화되는 문제를 겪었어. 영철이는 React Router 철학대로 거대한 App.tsx 에서 모든 상태를 관리하려다 유지보수 난맥(Maintenance Nightmare) 에 빠지고 만 거야.

영호(FE 리드) 가 한숨을 쉬며 다가왔어. "영철아, Next.js App Router 의 layout.tsx 가 왜 존재하는지 아직 모르는구나. 변하지 않는 배경과 변하는 주인공을 파일 단위로 쪼개야 해."

Next.js App Router 는 "폴더 이름이 곧 URL 이고, 파일 이름이 곧 역할이다" 라는 강력한 원칙 제공해. 특정한 예약어 파일들(layout.tsx, template.tsx, loading.tsx) 의 동작 방식과 생존 주기(생명주기) 를 모르면, 불필요한 재렌더링에 영원히 고통받게 될 거야.

🏗️ 비유로 먼저 이해하기

🤔 잠깐, 먼저 생각해봐
우리가 사는 집을 떠올려보자. 거실의 벽지는 그대로인데, TV 속 화면만 바뀌는 것과 거실 인테리어 전체를 매번 다 뜯어고치는 것 중 무엇이 더 효율적일까?

🖼️ 마트료시카 인형과 액자 비유

Next.js 의 라우팅 구조는 겹겹이 쌓인 액자 프레임 과 같아.

• layout.tsx: 가장 바깥쪽의 튼튼한 나무 액자 틀. 안의 그림을 아무리 바꿔 끼워도, 바깥 액자 틀은 전혀 움직이거나 부서지지 않아. (상태가 영원히 유지됨)
• page.tsx: 액자 속 알맹이 그림. URL 이 바뀔 때마다 교체되는 핵심 내용이야.
• template.tsx: 생김새는 layout 과 비슷한데, 그림 교체할 때마다 액자 틀까지 초기화하고 새 액자로 다시 갈아 끼우는 예민한 대상 이야. 애니메이션 실행이나 초기화를 강제할 때 쓰지.

🧒 5살에게 설명한다면?
"레이아웃은 튼튼한 우리 집 벽이야. 우리가 거실에서 방으로 가도 벽은 그대로지? 하지만 템플릿은 우리가 방에 들어갈 때마다 매번 새로 켜지는 조명 같은 거야!"

💡 한 줄로 기억하기
Layout 은 보존, Template 은 재생성이다.

📄 page.tsx와 layout.tsx의 공생 관계 🟢

🎯 이 섹션을 읽고 나면:

• Next.js 가 화면을 조립할 때 부모-자식 관계가 어떻게 유지되는지 설명할 수 있다.
• 상태 보존을 위해 왜 Layout 을 써야 하는지 기술적으로 증명할 수 있다.

1. page.tsx: 라우트의 유일한 주인공

해당 주소(/studies)로 접근했을 때 그려지는 메인 UI야.

2. layout.tsx: 변하지 않는 든든한 배경

자식 라우트 사이를 이동할 때 상태(State)를 보존하고 리렌더링을 차단해주는 일등 공신이야. 영철이의 고민이 여기서 해결되지.

❌ 순진한 코드 (Naive Approach)
페이지 트랜지션 로직을 page.tsx 최상단 부모에서 무리하게 조작해 화면 깜빡임 유발.

✅ 우아한 코드 ( Pro Approach ) - 영호의 해결책

// app/studies/layout.tsx
// 🦁 영호: "이 파일은 URL이 바뀌어도 절대 다시 렌더되지 않고 굳건히 버팁니다."
 
export default function StudiesLayout({ children }: { children: React.ReactNode }) {
  return (
    <div className="flex">
      {/* 🐣 영철: "와! 이제 필터에 적어둔 검색어가 안 사라져요!" */}
      <nav>강력한 스터디 검색 사이드바 필터 (상태 유지됨)</nav>
 
      {/* 🦁 영호: "children 자리의 page.tsx만 부드럽게 교체되는 겁니다." */}
      <main className="flex-1">{children}</main>
    </div>
  )
}

💡 한 줄로 기억하기
Page 는 매번 바뀌는 주인공, Layout 은 그 주인공을 지켜주는 무대 배경이다.

🧩 layout.tsx vs template.tsx — 무엇이 다를까? 🟡

🤔 잠깐, 먼저 생각해봐
영숙(디자이너)이가 요구했어. "스터디 탭 페이지 이동할 때마다 화면이 왼쪽에서 슈웅~ 나타나게 (Framer Motion) 해주세요! 그리고 이동할 때마다 페이지 뷰(GA) 이벤트도 쏘아주시고요."
이걸 절대 리렌더링되지 않는 철벽방어 layout.tsx에 붙여두면 어떻게 될까?

이게 뭔가?

template.tsx는 문법적으로 layout과 완전 동일({ children } 패턴)하지만, 사용자가 자식 라우트로 진입/변경할 때마다 DOM을 새로 마운트(Re-mount)해버리는 파일이야.

실무에서 어떻게 활용되는가?

useEffect 를 이용해 '경로 방문 시 1회 발동' 하는 로직이나 트랜지션 애니메이션을 붙일 때 완벽해.

// app/studies/template.tsx
'use client' // 🎨 영숙: "애니메이션은 클라이언트에서 돌아가야 하니까요!"
import { useEffect } from 'react'
 
export default function StudyTemplate({ children }: { children: React.ReactNode }) {
  useEffect(() => {
    // 🦁 영호: "탭을 누를 때마다 여기가 발동되는 마법을 보세요."
    console.log('📌 페이지 뷰 전환 이벤트 수집 발동!')
  }, [])
 
  return <div className="animate-slide-in">{children}</div>
}

💡 한 줄로 기억하기
필터 값을 지키고 싶다면 Layout, 클릭할 때마다 불꽃놀이를 터뜨리고 싶다면 Template 이다.

🔀 layout.tsx + template.tsx 함께 쓰면? 🟡

🎯 이 섹션을 읽고 나면:

• 같은 폴더에 layout.tsx와 template.tsx가 공존할 때 렌더 순서를 설명할 수 있다
• 두 파일의 역할을 분리해서 실무에 응용할 수 있다

둘이 공존할 수 있어?

결론부터 말하면 완벽하게 공존 가능해. Next.js는 같은 폴더에 layout.tsx와 template.tsx가 모두 있으면 이 순서대로 감싸서 렌더해:

layout.tsx
  └─ template.tsx
       └─ page.tsx

즉 layout이 가장 바깥쪽, template이 그 안쪽, page가 알맹이 구조야.

언제 이렇게 쓸까?

영수네 커뮤니티 상황이야. 영호가 스터디 리스트 페이지에 두 가지를 동시에 원해:

• 검색 필터 사이드바 상태를 URL 이동 중에도 유지해야 한다 (→ layout)
• 탭을 눌러 새 스터디 목록으로 이동할 때마다 페이지 진입 애니메이션과 GA 이벤트를 쏴야 한다 (→ template)

// app/studies/layout.tsx ← 바깥쪽 (영구 생존, 상태 보존)
export default function StudiesLayout({ children }) {
  return (
    <div className="flex">
      <Sidebar />  {/* URL이 바뀌어도 이 사이드바는 절대 사라지지 않음 */}
      <main>{children}</main>
    </div>
  )
}

// app/studies/template.tsx ← 안쪽 (탭 이동마다 강제 재마운트)
'use client'
import { useEffect } from 'react'
 
export default function StudiesTemplate({ children }) {
  useEffect(() => {
    // 탭을 누를 때마다(URL 변경 시) 여기가 발동됨 ← template이기 때문
    sendGAEvent('page_view', { path: window.location.pathname })
  }, [])
 
  return (
    <div className="animate-fade-in">  {/* 슈웅~ 페이드인 애니메이션 */}
      {children}
    </div>
  )
}

// app/studies/[category]/page.tsx ← 알맹이 (카테고리별로 교체됨)
export default function StudyListPage({ params }) {
  return <StudyList category={params.category} />
}

결과:

• 사이드바 필터 상태 → layout이 버텨줘서 URL 이동 후에도 보존 ✅
• 페이드인 애니메이션 + GA 이벤트 → template이 매번 재마운트되며 발동 ✅

렌더 순서 정리

🤔 잠깐, 먼저 생각해봐
만약 layout 안에 template 이 있는 게 아니라, 반대로 template 이 layout 을 감싸고 있다면 어떤 문제가 생길까? (힌트: 상태 유지)

[URL: /studies/frontend 진입]
1. layout.tsx 마운트 (최초 1회, 이후 보존)
2. template.tsx 마운트 (진입마다 새로 마운트)
3. page.tsx 렌더 (URL 변경마다 교체)
 
[URL: /studies/backend 이동 시]
1. layout.tsx → 유지 (사이드바 상태 살아있음) ✅
2. template.tsx → 초기화 후 새로 마운트 (애니메이션/GA 발동) 🔄
3. page.tsx → 새 카테고리로 교체 🔄

💡 한 줄로 기억하기
Layout 은 영구적인 근거지, Template 은 그 안에서 탭마다 새로 지어지는 텐트와 같다.

🎭 라우트 그룹 (folder)의 마법 🟡

영수네 커뮤니티에는 일반 유저들이 보는 **"스토어/스터디 메인 영역"**과 영수만 들어가는 "관리자 어드민(admin)" 영역이 있어.
이 둘은 사이드바 모양, 헤더까지 180도 다르게 생겼지.

❌ 순진한 코드 (Naive Approach)
루트 최상단 app/layout.tsx 파일 내에서 길고 지저분한 if (pathname.includes('admin')) return AdminLayout 형태의 삼항 연산자를 넣어버리는 오래된 방식의 분기 처리. 서버와 클라이언트 컴포넌트 간 오염 발생.

✅ 우아한 코드 ( Pro Approach ) - 라우트 그룹 적용
폴더 이름 앞뒤에 괄호 () 를 묶어주어 "URL 경로에서는 완전히 생략" 하면서 "조직적인 파일 그룹" 을 만들어내.

app/
 ├─ (consumer)/
 │   ├─ layout.tsx      // 🎨 영숙: "일반 유저용 깔끔한 레이아웃"
 │   ├─ page.tsx        // url: '/'
 │   └─ studies/page.tsx// url: '/studies'
 │
 └─ (admin)/
     ├─ layout.tsx      // 👔 영수: "시커먼 어드민 전용 사이드바 레이아웃!"
     └─ dashboard/page.tsx // url: '/dashboard'

이 구조 덕분에, 완벽히 고립된 최상위 레이아웃을 2개 이상 가질 수 있게 돼!

💡 한 줄로 기억하기
Route Group 은 URL 에 흔적을 남기지 않는 유령 폴더이자, 레이아웃 분리 수거함이다.

💥 에러 해결 카탈로그

❌ You cannot define a route with the same specificity...

원인: (consumer)/page.tsx 와 (admin)/page.tsx 를 둘 다 만들어 버렸음.
괄호 레이어는 URL에서 무시되므로, 두 페이지 모두 인터넷 주소로는 / 최상위를 바라보게 되어 충돌이 발생해.
해결책: 깊이가 겹치는 루트 페이지 라우팅 시에는 그룹 중 하나에만 배치하거나 폴더 경로를 명시해야 해.

🏁 이번에 배운 내용 총정리

오늘 배운 핵심을 한눈에 정리해볼까? 실무에서 길을 잃었을 때 이것만 봐도 돼.

📋 특수 파일명 역할 요약

⚠️ 절대 하지 말 것 ( 안티 패턴 )

📝 마무리 퀴즈

Q1. layout.tsx와 template.tsx의 가장 중요한 차이는?

✅ 정답: layout은 라우트 이동에도 상태를 보존하고, template은 이동마다 새 인스턴스를 만든다.

💡 상세 해설: 검색 입력, 탭 상태처럼 유지되어야 하는 UI는 layout에 어울린다. 매 이동마다 초기화되어야 하는 애니메이션이나 폼 흐름은 template이 더 적절할 수 있다.

Q2. Route Group을 쓰면 URL에는 어떤 변화가 생기나?

✅ 정답: 괄호 폴더는 URL에 나타나지 않는다.

💡 상세 해설: (admin), (marketing) 같은 그룹은 레이아웃과 코드 조직을 나누지만 주소를 바꾸지 않는다. URL 설계와 폴더 설계를 분리할 수 있는 장치다.

Q3. 영철이의 테스트 타임: 관리자 화면과 공개 화면의 헤더가 완전히 다르지만 URL은 /admin으로 유지하고 싶다. 어디를 조정할까?

✅ 정답: app 폴더에서 route group과 layout 경계를 나눠 관리자 전용 layout을 둔다.

💡 상세 해설: 페이지마다 조건문으로 헤더를 바꾸기보다 라우트 구조가 레이아웃 책임을 갖게 하는 편이 유지보수에 좋다. 예약 파일 이름은 프레임워크와 맺는 계약이다.

🐣 영철이의 퇴근 일기

오늘은 app 폴더가 단순한 파일 모음이 아니라 라우팅 계약서라는 걸 배웠다.

💡 "예약 파일은 이름이 곧 프레임워크와 맺는 약속이다."

앞으로 폴더를 만들 때 URL, 레이아웃 보존, 초기화 범위를 함께 메모하겠다.

🔗 더 알아보기

• Next.js Docs: Routing Fundamentals