페이지 컴포넌트 작성

이제까지 Next.js App Router의 기본적인 라우팅 원리와 구조에 대해 충분히 익히셨을 겁니다.

이제 그 핵심인 페이지 컴포넌트(Page Component)를 어떻게 효과적으로 작성하고 활용하는지 심도 있게 다룰 차례입니다.

페이지 컴포넌트는 특정 URL의 고유한 화면을 정의합니다. 상위 레이아웃이 제공하는 공통 UI 안에 렌더링됩니다.

이 절에서는 페이지 컴포넌트의 기본적인 역할부터 데이터 페칭, 그리고 동적인 파라미터 활용까지, 실제 애플리케이션 개발에 필요한 구체적인 작성 방법을 살펴보겠습니다.

페이지 컴포넌트의 역할과 특징

App Router에서 페이지 컴포넌트는 app 디렉터리 내의 특정 라우트 세그먼트 폴더 안에 위치한 page.tsx (또는 .js, .jsx) 파일입니다.

• URL 매핑: app/your-route/page.tsx 파일은 your-route 경로에 접근했을 때 렌더링되는 UI를 정의합니다.
• 최종 UI 렌더링: 레이아웃 컴포넌트와 달리, 페이지 컴포넌트는 children prop을 받지 않습니다. 대신, 레이아웃의 children prop 위치에 자신만의 고유한 UI를 렌더링합니다.
• 기본적으로 서버 컴포넌트: 별도의 "use client" 지시어가 없다면, 페이지 컴포넌트는 서버 컴포넌트로 동작합니다. 이는 페이지 컴포넌트 내에서 직접 데이터베이스에 접근하거나 서버 전용 코드를 작성할 수 있음을 의미합니다.
• 비동기 함수 지원: 서버 컴포넌트인 페이지 컴포넌트는 async / await 문법을 사용하여 비동기 데이터 페칭을 직접 수행할 수 있습니다.

기본적인 페이지 컴포넌트 작성하기

가장 기본적인 페이지 컴포넌트는 단순한 React 함수 컴포넌트와 동일하게 작성됩니다.

// 이 컴포넌트는 기본적으로 서버 컴포넌트로 동작합니다.
export default function WelcomePage() {
  return (
    <div>
      <h2>새로운 환영 페이지</h2>
      <p>Next.js App Router로 만든 간단한 페이지입니다.</p>
    </div>
  );
}

실습: src/app/welcome 폴더를 만들고 그 안에 page.tsx 파일을 위 내용으로 생성한 다음, http://localhost:3000/welcome으로 접속해 보세요.

페이지가 정상적으로 렌더링되는 것을 확인할 수 있습니다.

페이지 컴포넌트에서 데이터 페칭하기

페이지 컴포넌트가 서버 컴포넌트라는 점은 데이터 페칭에서 엄청난 강점을 발휘합니다.

서버에서 데이터를 조회해 콘텐츠를 포함한 HTML을 보낼 수 있습니다. 실제 응답 시간은 API 지연, 캐시와 렌더링 방식에 따라 달라집니다.

실습 재현성을 위해 본 절의 API 예시는 로컬 Mock 서버(json-server, http://localhost:4000)를 기준으로 작성합니다.

포트 정책은 4000=Mock API, 4100=별도 백엔드/실시간 서버로 분리해 두면 다른 트랙 실습과 동시에 실행해도 충돌을 줄일 수 있습니다.

예시: 목록과 상세가 함께 사용할 데이터 준비

명령을 실행할 작업 폴더에 다음 db.json을 먼저 만듭니다. 세 항목은 이 절의 최소 실습 데이터이며, 인기순·실제 서비스의 데이터가 아닙니다. id는 숫자이고 title, body는 문자열이므로 아래 목록의 substring과 상세 화면에 필요한 값이 들어 있습니다.

{
  "posts": [
    { "id": 1, "title": "페이지의 역할", "body": "page.tsx는 이 URL에서 보여줄 본문을 만듭니다." },
    { "id": 2, "title": "링크와 경로", "body": "목록의 숫자 id를 링크에 넣으면 상세 경로가 됩니다." },
    { "id": 3, "title": "상세 데이터", "body": "URL의 문자열 id로 같은 게시물의 상세 데이터를 조회합니다." }
  ]
}

아래 명령은 학습자의 별도 Next.js 프로젝트에서 사용할 API 실행 안내입니다. Next.js 개발 서버와 Mock API는 서로 다른 프로세스이므로 둘 다 실행되어야 합니다. 프로젝트에 이미 사용하는 db.json이 있다면 덮어쓰기보다 별도 실습 폴더나 백업을 사용합니다.

실행 전 npx [email protected] --watch db.json --port 4000으로 mock 서버를 띄웁니다. 이 버전의 _limit 쿼리와 숫자 ID를 기준으로 하며, db.json에는 숫자 id, 문자열 title, body를 가진 posts 배열이 있어야 합니다. generateStaticParams를 실행하는 빌드에서도 이 API에 접근할 수 있어야 합니다.

페이지 컴포넌트 내에서 async 함수로 데이터를 가져올 수 있습니다.

데이터가 준비되면 페이지 콘텐츠를 완성합니다. Suspense 경계가 있으면 대기 중인 부분의 로딩 UI를 먼저 전송할 수 있습니다. 아래 revalidate는 주석이므로 현재 코드에 재검증 캐시 정책을 적용하지 않습니다.

import Link from 'next/link';

interface Post {
  id: number;
  title: string;
  body: string;
}

// 이 함수는 서버에서 실행되어 데이터를 가져옵니다.
async function getPosts(): Promise<Post[]> {
  const res = await fetch('http://localhost:4000/posts?_limit=20', {
    // revalidate 옵션을 사용하여 데이터 캐싱 전략을 지정할 수 있습니다.
    // next: { revalidate: 60 } // 60초 이상 지난 뒤 다음 요청을 계기로 재검증
  });
  if (!res.ok) {
    // 에러 발생 시 처리
    throw new Error('Failed to fetch posts');
  }
  const payload = await res.json();
  return payload;
}

export default async function PostsPage() { // async 키워드를 붙여 비동기 컴포넌트로 만듭니다.
  const posts = await getPosts(); // 서버에서 데이터 페칭

  return (
    <div>
      <h1>모든 게시물</h1>
      <ul>
        {posts.map((post) => (
          <li key={post.id} style={{ marginBottom: '15px', border: '1px solid #eee', padding: '10px' }}>
            <h3>{post.title}</h3>
            <p>{post.body.substring(0, 100)}...</p>
            {/* Link 컴포넌트로 동적 라우트 연결 */}
            <Link href={`/posts/${post.id}`}>더 보기</Link>
          </li>
        ))}
      </ul>
    </div>
  );
}

실습: src/app/posts 폴더를 만들고 그 안에 page.tsx 파일을 위 내용으로 생성합니다.

그리고 동적 라우트를 위한 src/app/posts/[id]/page.tsx 파일도 다음과 같이 생성합니다.

import Link from 'next/link';

interface PostDetailPageProps {
  params: Promise<{
    id: string; // URL에서 추출될 게시물 ID
  }>;
}

interface Post {
  id: number;
  title: string;
  body: string;
}

// 특정 게시물 데이터를 가져오는 함수
async function getPost(id: string): Promise<Post> {
  const res = await fetch(`http://localhost:4000/posts/${id}`);
  if (!res.ok) {
    throw new Error('Failed to fetch post');
  }
  return res.json();
}

// 동적 라우트를 위한 generateStaticParams (SSG 사용 시)
export async function generateStaticParams() {
  const res = await fetch('http://localhost:4000/posts?_limit=20');
  const payload = await res.json();
  const posts: Post[] = payload;

  // 상위 10개의 게시물만 미리 생성하도록 제한 (실제 프로젝트에서는 전체 또는 필요한 부분만)
  return posts.slice(0, 10).map((post) => ({
    id: post.id.toString(), // id는 문자열이어야 합니다.
  }));
}

export default async function PostDetailPage({ params }: PostDetailPageProps) {
  const { id } = await params;
  const post = await getPost(id); // 서버에서 특정 게시물 데이터 페칭

  return (
    <div>
      <h1>{post.title}</h1>
      <p>{post.body}</p>
      <Link href="/posts">목록으로 돌아가기</Link>
    </div>
  );
}

http://localhost:3000/posts로 접속하여 게시물 목록을 확인하고, 각 게시물의 더 보기 링크를 클릭하여 상세 페이지로 이동해 보세요.

generateStaticParams의 주석에 적힌 “상위 10개”는 응답 배열의 앞 10개를 뜻하며 인기순 정렬은 없습니다. 미리 생성하지 않은 ID도 기본 정책에서는 요청 시 처리할 수 있습니다.

현재 getPost는 404를 포함한 실패 응답에 Error를 던집니다. 없는 게시물을 전용 404 화면으로 보이게 하려면 상태를 구분해 notFound()를 호출해야 합니다. 타입 선언은 외부 JSON의 모양을 실행 시 검증하지 않습니다.

따라 해 보기: 한 게시물이 목록에서 상세로 이어지는지 확인하기

1. Mock API를 시작한 뒤 http://localhost:4000/posts와 http://localhost:4000/posts/3에서 JSON이 나오는지 먼저 확인합니다. 페이지 오류를 조사하기 전에 API가 실행되어 있고 body가 문자열인지 확인할 수 있습니다.
2. 기존 Next.js 프로젝트의 개발 서버를 실행하고 /posts에서 세 제목이 보이는지 확인합니다. 세 번째 더 보기를 누르면 주소는 /posts/3이 되고, await params로 받은 값은 숫자 3이 아니라 문자열 "3"입니다.
3. 상세 화면에 세 번째 body가 표시되는지 확인하고 목록으로 돌아가기를 누릅니다. 링크는 데이터를 전달하는 함수 호출이 아니라 상세 URL로 탐색하는 UI입니다. 상세 페이지가 그 URL의 id로 다시 조회합니다.
4. 빌드를 확인할 때도 Mock API가 실행 중이어야 합니다. 이 세 항목에서 slice(0, 10)은 세 항목을 모두 선택합니다. API를 끈 상태의 빌드 실패를 라우트 폴더 이름만의 문제로 판단하지 않습니다.

스스로 확인하기

다른 실습 데이터에 숫자 ID가 1부터 12까지 순서대로 있고 API가 이 배열을 그대로 반환한다고 가정합니다. 현재 generateStaticParams의 반환 항목 수와 첫 항목의 id 타입은 무엇인가요? 미리 생성 후보에 없는 /posts/12는 곧바로 404가 되나요? API의 /posts/99가 실패 응답을 보내면 현재 코드에서 어떤 경로를 따르나요?

동적 파라미터 params 활용하기

동적 라우트([slug], [id] 등)를 정의한 경우, 페이지 컴포넌트는 params라는 prop을 통해 URL에서 추출된 동적인 값을 전달받습니다.

이는 페이지 콘텐츠를 해당 파라미터에 따라 다르게 렌더링할 때 사용됩니다.

위 src/app/posts/[id]/page.tsx 예시에서는 await params로 id를 꺼내 특정 게시물의 데이터를 가져왔습니다.

다음은 prop 타입을 읽기 위한 부분 코드입니다. [id]와 다른 키의 폴더를 같은 위치에 추가하는 지시가 아니며, 생략한 반환 UI를 채워야 완전한 페이지가 됩니다.

// 페이지 컴포넌트의 prop 타입 정의
interface MyPageProps {
  params: Promise<{
    dynamicParamName: string; // [dynamicParamName]
    // 만약 Catch-all 세그먼트 [[...slug]]라면:
    // slug?: string[];
  }>;
  searchParams?: Promise<{ [key: string]: string | string[] | undefined }>; // 쿼리 파라미터 (다음 절에서 다룸)
}

export default async function MyDynamicPage({ params }: MyPageProps) {
  const { dynamicParamName } = await params;
  // ...
}

params 객체의 키(key)는 폴더 이름의 대괄호 안에 정의된 이름([dynamicParamName])과 정확히 일치해야 합니다.

페이지 컴포넌트의 추가 기능 (선택 사항)

• loading.tsx와 함께 사용: 데이터 페칭 중인 동안 사용자에게 로딩 UI를 보여주고 싶다면, 해당 페이지 컴포넌트와 동일한 라우트 세그먼트 폴더에 loading.tsx 파일을 생성하면 됩니다.

  export default function Loading() {
    return <div>게시물 목록을 불러오는 중입니다...</div>;
  }

  /posts의 해당 경계가 대기할 때 이 메시지를 사용할 수 있습니다. 콘텐츠가 이미 준비되었거나 사전 로드되어 있다면 메시지가 눈에 보이지 않을 수도 있습니다.

• error.tsx와 함께 사용: 페이지 컴포넌트나 그 하위 컴포넌트에서 에러가 발생했을 때 사용자에게 친절한 에러 메시지를 보여주고 싶다면, error.tsx 파일을 생성할 수 있습니다.

  "use client"; // Error Boundaries는 클라이언트 컴포넌트여야 합니다.
  
  import { useEffect } from 'react';
  
  export default function Error({
    error,
    reset,
  }: {
    error: Error & { digest?: string };
    reset: () => void;
  }) {
    useEffect(() => {
      // 에러 로깅 서비스 등에 에러를 기록할 수 있습니다.
      console.error(error);
    }, [error]);
  
    return (
      <div>
        <h2>문제가 발생했습니다!</h2>
        <p>{error.message}</p>
        <button
          onClick={
            // 에러를 재설정하고 다시 시도합니다.
            () => reset()
          }
        >
          다시 시도
        </button>
      </div>
    );
  }

  error.tsx 파일은 클라이언트 컴포넌트여야 하며, 이 경계 아래의 렌더링 오류를 처리합니다. 같은 세그먼트의 layout.tsx나 이벤트 핸들러의 오류까지 모두 잡는 것은 아닙니다.