🚀 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.tsx

💡 상세 해설:

• 원리 설명: 폼 데이터(State) 를 보존하려면 URL 이동 간 컴포넌트가 파괴(Unmount) 되지 않아야 해. layout.tsx 는 자식 경로가 바뀌어도 상태를 끝까지 지켜주는 철벽 방어막 역할을 하기 때문이야.
• 오답 피드백: "영철 님, template.tsx 를 쓰는 순간 유저가 탭을 누르자마자 정성껏 쓴 글자가 안개처럼 증발해 버릴 거예요!"
• 📌 핵심 기억법: "금쪽같은 유저 데이터는 레이아웃에 맡겨라."

Q2. 영호(리드) 가 특정 파일 트리 안에 (auth) 라는 폴더를 팠고 내부로 로그인을 옮겼다. 이렇게 라우트 그룹을 생성함으로써 얻는 가장 강력한 "아키텍처적 장점"은 무엇인지 URL 제어의 관점이 아닌 layout 의 관점에서 설명하라.

✅ 정답: 특정 목적(인증, 어드민 등) 에 맞게 뼈대(Layout) 를 완전히 쪼개서 고립시킬 수 있다.

💡 상세 해설:

• 관심사 분리: 로그인 페이지(여백 가득) 와 메인 대시보드(사이드바 복잡) 의 레이아웃을 하나의 부모 밑에서 지저분한 조건문 없이 물리적으로 분리할 수 있어.
• 비즈니스 가치: 인증 영역에만 특별한 보안 헤더나 로직을 적용하기가 매우 수월해져서 유지보수가 우아해지지.
• 📌 핵심 기억법: "라우트 그룹은 레이아웃의 구원자다."

🐣 영철이의 퇴근 일기

오늘 App Router의 구조를 배우면서 넥스트의 거대한 보물을 발견한 기분이야! 특히 '공유되는 반찬통(Layout)' 과 '매번 새로 차리는 국밥(Page)' 의 조화는 정말 예술이더라고.

💡 오늘의 교훈: "변하는 것(Page) 과 변하지 않는 것(Layout) 을 명확히 분리하여 브라우저의 일손을 덜어주자!"

그동안 페이지를 옮길 때마다 모든 걸 다 지웠다 다시 그렸던 내 지난날들이 영호 리드 님의 팩폭과 함께 스쳐 지나갔지만... 뭐 어때! 이제라도 제대로 된 구조를 알았으니 됐지! 오늘 집중력 좋았다. 집에 가서 시원한 맥주 한 캔 따고 푹 쉬어야겠어. 내일은 내가 오늘 배운 레이아웃 설계 능력을 뽐내서 영호 님을 깜짝 놀라게 해드려야지! 🐣

🔗 더 알아보기

• Next.js Docs: Routing Fundamentals