Next.js App Router 자동 실행 규칙

특정 이름의 함수나 파일 구조만으로도 Next.js가 자동으로 코드를 실행해 주는 기능이 존재합니다.

이러한 규칙을 이해하면 데이터 패칭, SEO 메타데이터 구성, 정적 페이지 생성 등 다양한 기능을 예측 가능하고 깔끔하게 구현할 수 있습니다.

 

Next.js가 자동으로 호출하는 함수들

Next.js는 특정한 이름의 함수를 해당 라우트 파일 내에 export 하게 되면, 이를 예약된 서버 함수(Server Special Functions) 로 인식하고 자동으로 실행합니다.

 

---

 

주요 자동 실행 함수 목록

generateMetadata()

SEO 메타 정보(title, description, og:image 등)를 페이지 렌더링 전에 자동으로 생성하는 함수입니다.

export async function generateMetadata({ params }) {
  const user = await getUser(params.username);
  return {
    title: user.name,
    description: user.bio,
  };
}

• 호출 시점: 페이지가 렌더링되기 직전
• 실행 위치: 서버에서만 실행
• 사용 목적: SEO 최적화, SNS 공유용 메타 태그 설정

 

generateStaticParams()

정적 빌드 시, 동적 라우트의 모든 가능한 파라미터를 미리 생성해야 할 때 사용됩니다.

export async function generateStaticParams() {
  const users = await getAllUsers();
  return users.map(user => ({ username: user.username }));
}

• 호출 시점: 빌드 타임 (또는 ISR 시점)
• 사용 목적: 정적 페이지 생성 (SSG)

 

generateViewport()

특정 페이지에 필요한 viewport 메타 태그를 자동으로 생성합니다.

export function generateViewport() {
  return {
    themeColor: "#000000",
  };
}

 

 

 

---

왜 호출 없이 실행되는가? (자동 실행 원리)

Next.js App Router는 파일 기반 라우팅과 함께, 파일 내에서 export된 특정 예약 함수 이름을 스캔하여 페이지 렌더링 라이프사이클 단계마다 자동 실행합니다.

 

Next.js의 수행 순서는 다음과 같습니다

사용자 요청 → 라우트 매칭 → generateMetadata() → 서버 컴포넌트 렌더링 → 클라이언트로 전송

 

즉, 우리가 직접 호출하지 않아도 Next.js가 다음처럼 수행

• 라우트 파일을 분석 (빌드 or 요청 시)
• generateMetadata 가 있으면 SEO 단계에서 자동 호출
• generateStaticParams 가 있으면 빌드 타임에서 자동 호출

이 모든 것이 Next.js의 기획된 동작이기 때문에, 개발자가 직접 generateMetadata() 같은 함수를 호출하는 일은 없습니다.

 

---

 

📌 3. 자동 실행 함수의 공통 특징

모든 자동 실행 함수들은 다음과 같은 특징을 공유합니다.

특징	내용
실행 위치	서버에서만 실행됨 (Server Environment)
호출 방식	직접 호출 X → Next.js가 자동 호출
목적	SEO, 데이터 준비, 정적 페이지 생성
실행 시점	라우트별 렌더링 전에 단계별 자동 실행

 

특히 generateMetadata()는 클라이언트 렌더링 및 hydration 이전 단계에서 반드시 처리되어야 하는 SEO 함수이기 때문에 자동 호출됩니다.

 

 

---

왜 이런 자동 실행 기능이 필요한가?

Next.js는 App Router에서 다음 목표를 갖고 있습니다

• SEO 최적화 자동화
• 데이터 패칭 전략 단순화
• 서버/클라이언트 분리 명확화
• SSR/SSG/ISR 통합 설계

이를 위해, 아래처럼
“함수 이름만 써도 동작하는 예약 함수” 패턴을 도입했습니다.

기존 Pages Router의 getServerSideProps, getStaticProps, getStaticPaths와 유사한 개념이지만 더 직관적이고 기능별로 세분화된 형태입니다.