Next.js(App Router)에서 layout.tsx, page.tsx 개념 정리

대상: Next.js 13+ App Router (app/ 디렉터리 기반)
핵심: 폴더 구조가 곧 URL이며, page.tsx는 “페이지”, layout.tsx는 “공용 틀(프레임)”이다.

---

1. App Router 기본 규칙

1) 라우팅은 폴더 구조로 결정된다

Next.js App Router에서는 app/ 디렉터리 아래의 폴더 구조가 URL 경로를 결정한다.

• app/login/page.tsx → /login
• app/signin/page.tsx → /signin
• app/admin/users/page.tsx → /admin/users

즉, page.tsx 파일이 존재하는 폴더가 하나의 라우트(경로)이다.
page.tsx가 없으면 해당 경로는 페이지로 동작하지 않는다.

2) 컴포넌트는 기본이 Server Component이다

App Router에서는 모든 컴포넌트가 기본적으로 Server Component로 동작한다.

브라우저에서 다음 기능을 사용하려면 Client Component로 선언해야 한다.

• 상태 관리 (useState)
• 라이프사이클 훅 (useEffect)
• 이벤트 핸들러 (onClick, onSubmit 등)
• 클라이언트 라우터 (useRouter)
• 폼 라이브러리(Formik, React Hook Form 등)

Client Component 선언 방법:

"use client";

---

2. page.tsx란?

1) 역할

page.tsx는 특정 URL에서 실제로 렌더링되는 화면을 정의한다.

각 라우트 폴더에는 반드시 page.tsx가 존재해야 페이지로 인식된다.

2) 예시 (ex)

app/
  signin/
    page.tsx

3) page.tsx에서 주로 하는 일

• 해당 페이지 전용 UI 배치 (센터 정렬, 컨테이너 폭, 페이지 타이틀 등)
• 폼, 리스트, 테이블 등 실제 콘텐츠 렌더링
• Client component인 경우 : 이벤트 처리 및 상태 관리

---

3. layout.tsx란?

1) 역할

layout.tsx는 해당 폴더(세그먼트) 아래 모든 페이지에 공통으로 적용되는 프레임(틀)이다.

한 번 정의하면, 그 하위의 모든 page.tsx는 이 레이아웃 안에서 렌더링된다.

2) 예시 (ex)

app/
  (auth)/
    layout.tsx
    signin/
      page.tsx
    verify-email/
      page.tsx

• (auth) 아래에 있는 모든 페이지는 동일한 레이아웃을 공유한다.

3) layout.tsx에서 주로 하는 일

• 공통 헤더, 푸터, 사이드바
• 공통 Provider 설정 (ThemeProvider, ApolloProvider, QueryClientProvider, ToastProvider 등)
• 공통 스타일 설정 (배경색, padding, min-height 등)
• 세그먼트 단위 정책 (인증 가드, 접근 제어, 리다이렉트 등)

---

4. layout.tsx가 있는데 page.tsx에서도 레이아웃을 잡는 이유

1) 이유

두 파일의 역할 범위가 다르기 때문이다.

• layout.tsx > 여러 페이지가 공유하는 공통 구조
• page.tsx > 해당 페이지 하나만을 위한 전용 배치

2) 예시 ex

layout.tsx

• 사이트 전체 배경
• 공통 폰트
• Provider 설정

signin/page.tsx

• 로그인 카드 중앙 정렬
• 카드 폭 제한
• 페이지 타이틀 배치

이것이 정상적인 구조이며, App Router의 권장 패턴이다.

---

5. layout.tsx는 여러 개가 중첩될 수 있다

1) 개념

App Router에서는 폴더마다 layout.tsx를 둘 수 있으며, 하위로 내려갈수록 레이아웃이 중첩 적용된다.

2) 예시 (ex)

app/
  layout.tsx                # 사이트 전체 공통
  (auth)/
    layout.tsx              # 인증 구간 공통
    signin/
      page.tsx
  (dashboard)/
    layout.tsx              # 대시보드 구간 공통
    e-wallet/
      page.tsx

3) /signin 접근 시 실제 적용 구조

app/layout.tsx
+ app/(auth)/layout.tsx
+ app/(auth)/signin/page.tsx

---

6. 자주 사용하는 특수 파일들

1) loading.tsx

해당 라우트 또는 세그먼트가 로딩 중일 때 표시되는 UI이다.

app/signin/loading.tsx

2) error.tsx

해당 라우트에서 에러가 발생했을 때 표시되는 UI이다.
대부분 Client Component로 작성

app/signin/error.tsx

3) not-found.tsx

404(Not Found) 페이지를 정의한다.

app/not-found.tsx

---

7. Route Group (auth) 같은 괄호 폴더

1) 의미

(auth)처럼 괄호로 감싼 폴더는 URL 경로에 포함되지 않는다.
이 폴더는 구조와 레이아웃을 묶기 위한 용도이다.

app/(auth)/signin/page.tsx # 예시
/signin # 실제 URL

---

8. 폴더 구조로 이해하는 관점 정리

1) URL

• app/ 아래 폴더 구조로 결정된다.

2) 공통 틀

• 여러 페이지가 공유해야 하면 해당 폴더에 layout.tsx를 둔다.

3) 한 페이지

• 실제 화면은 page.tsx가 담당한다.

4) 재사용 UI

• components/ 폴더 또는 같은 폴더 내 컴포넌트로 분리한다.

---

9. 실무에서의 권장 구조 예시 (인증 영역)

1) 폴더 구조 (ex)

app/
  (auth)/
    layout.tsx
    signin/
      page.tsx
    forgot-password/
      page.tsx
    verify-email/
      page.tsx
components/
  AuthForm.tsx

2) 역할 분리

• (auth)/layout.tsx : 인증 페이지 공통 배경 및 센터링
• signin/page.tsx : 로그인 화면
• forgot-password/page.tsx : 비밀번호 재설정 화면
• AuthForm.tsx: 폼 로직 재사용

---

10. 한 줄 요약

• page.tsx는 URL 하나에 대응하는 화면이다.
• layout.tsx는 해당 구간 페이지들이 공유하는 공용 틀이다.
• 폴더 구조가 곧 라우트 구조이다.
• (group) 폴더는 URL에 나타나지 않는다.
• 기본은 Server Component이며, "use client"가 있으면 Client Component이다.

---

Next.js에서 백엔드로 API 요청 보내는 방식

GraphQL 기반의 API 통신 [graphql.tsx 파일]

• GraphQL 클라이언트: Apollo Client를 사용해 쿼리/뮤테이션을 보낸다. Apollo는 캐싱, 에러처리, 로딩 상태 등을 자동으로 관리
• 요청 방식: 클라이언트에서 useQuery (읽기) 또는 useMutation (쓰기)을 호출하면, Apollo가 자동으로 GraphQL 서버로 HTTP POST 요청을 보낸다. 요청 본문은 JSON 형식의 GraphQL쿼리/뮤데이션
• 엔드포인트: 단일 GraphQL 엔드포인트(예: https://your-backend.com/graphql)로 모든 요청이 간다. REST처럼 users, /posts 같은 여러 엔드포인트가 아니라, 하나의 엔드포인트에서 쿼리/뮤테이션으로 구분한다.