개발자 도구부터 연습용 사이트, 가볍게 써보는 생성기까지 한 번에 정리

최근 바이브코딩으로 작은 웹사이트들을 연달아 만들고 있다.

처음에는 단순히 “빨리 만들 수 있는지”를 확인하는 실험에 가까웠는데, 몇 개를 공개해보니 생각보다 방향이 분명해졌다. 큰 서비스 하나를 오래 붙잡는 방식보다, 실제로 필요한 작은 문제를 빠르게 풀고 바로 공개한 뒤 피드백으로 다듬는 방식이 지금은 더 잘 맞았다.

이번 글에서는 지금까지 공개한 웹사이트 14개를 한 번에 정리해보려고 한다.

내가 이 프로젝트들을 만들 때 기준은 단순했다.

첫째, 들어가자마자 설명 없이 바로 써볼 수 있을 것.
둘째, 특정 상황에서 다시 떠오를 만큼 목적이 분명할 것.
셋째, 완벽하지 않더라도 지금 당장 도움이 될 것.

이 기준으로 만들다 보니 자연스럽게 세 가지 종류로 나뉘었다.
개발하면서 바로 쓰는 도구, 짧게 연습해볼 수 있는 사이트, 그리고 가볍게 써보는 생성기나 허브형 프로젝트다.

1. 개발하면서 바로 쓰는 도구들

가장 먼저 만든 축은 개발 도구 쪽이다.

JSON Fixer는 깨진 JSON을 직접 고치면서 감을 익히는 연습용 사이트다.
실무에서는 문법 오류 하나 때문에 흐름이 끊기는 경우가 많아서, 이런 문제를 빠르게 눈에 익히는 데 초점을 맞췄다.

SQL Quiz는 SQL 쿼리 결과를 바로 실행하기 전에 먼저 예측해보는 방식의 퀴즈다.
SELECT, JOIN, GROUP BY 같은 구문은 “읽을 때 이해한 것”과 “실제로 결과를 맞히는 것” 사이에 차이가 있어서, 그 간극을 줄이는 용도로 만들었다.

Regex Playground는 정규식을 직접 넣고 테스트해볼 수 있는 연습 도구다.
정규식은 결국 손으로 많이 만져볼수록 익숙해지는 영역이라, 검색과 복붙 대신 직접 실험하는 흐름을 만들고 싶었다.

Tailwind Preview는 Tailwind CSS 클래스를 넣으면 결과를 빠르게 미리보는 도구다.
클래스 조합을 머릿속으로만 상상하지 않고 바로 확인할 수 있게 해두면 UI 프로토타이핑 속도가 꽤 빨라진다.

JSON to TypeScript 변환기는 JSON 데이터를 넣으면 TypeScript interface 초안을 만들 수 있게 한 도구다.
프론트엔드에서 API 응답을 타입으로 옮길 때 반복되는 작업을 줄이기 위해 만들었다.

Dev Toolbox는 개발하면서 자주 찾게 되는 작은 유틸리티를 모아둔 사이트다.
작은 기능 하나 때문에 검색 탭이 계속 늘어나는 게 번거로워서, 자주 쓰는 것들을 한 번에 묶어보는 방향으로 만들었다.

Utility Tools Hub는 개발자와 크리에이터가 두루 쓸 수 있는 온라인 도구를 모아본 허브다.
특정 기능 하나보다는 “어디서부터 시작할지 모를 때 들어가는 출발점”에 더 가깝다.

AI Prompt Generator는 작업 목적에 맞는 프롬프트 초안을 빠르게 만들어보는 도구다.
프롬프트를 매번 처음부터 쓰는 대신, 시작점을 빨리 잡는 데 의미를 두고 만들었다.

2. 짧게 연습해볼 수 있는 사이트들

두 번째 축은 연습형 사이트다.

티켓팅 보안문자 연습은 공연이나 콘서트 예매 전에 CAPTCHA 입력 감각을 빠르게 올려보는 용도로 만들었다.
티켓팅에서 보안문자는 의외로 체감 스트레스가 큰 요소라서, 이 부분만 따로 연습해볼 수 있게 해보고 싶었다.

Typing Speed Test는 가장 단순하게 타자 속도를 측정할 수 있는 사이트다.
복잡한 기능보다 “들어가서 바로 시작하고 바로 결과를 확인한다”는 흐름 자체에 집중했다.

이 두 프로젝트는 공통적으로 길게 설명할 필요가 없다.
짧게 들어갔다가 바로 써보고, 바로 결과를 얻고, 필요하면 다시 돌아오는 구조가 핵심이다.

3. 가볍게 써보는 생성기와 허브들

마지막은 비교적 가볍게 접근할 수 있는 사이트들이다.

랜덤 닉네임 생성기는 이름을 정해야 할 때 빠르게 후보를 얻는 용도로 만들었다.
생각보다 닉네임 하나 정하는 데 시간이 오래 걸릴 때가 많아서, 부담 없이 돌려보는 도구가 있으면 좋겠다고 생각했다.

한줄소개 생성기는 포트폴리오나 자기소개 첫 문장을 잡는 데 도움을 주기 위해 만들었다.
특히 취업 준비나 이직 준비 과정에서는 “첫 문장” 하나가 가장 막막한 경우가 많다.

Smart Calculator Hub는 다양한 온라인 계산기를 한데 모아둔 사이트다.
계산할 때마다 검색해서 다른 사이트를 전전하는 대신, 자주 쓰는 계산기를 한 곳에서 해결할 수 있도록 구성했다.

Fun Simulator Hub는 말 그대로 재미있는 랜덤 시뮬레이터를 모아둔 공간이다.
생산성보다는 가볍게 들어가서 한 번씩 돌려보는 재미에 더 가깝다.

만들면서 느낀 점

이 14개를 만들면서 가장 크게 느낀 건, 사람들이 거대한 기능보다도 “지금 바로 써볼 수 있는 작은 완성”에 더 빨리 반응한다는 점이었다.

서비스를 만드는 입장에서도 마찬가지였다.
큰 아이디어를 오래 품고 있는 것보다, 작은 문제를 분명하게 정의하고 빠르게 구현해보는 쪽이 훨씬 많은 걸 남겼다.
무엇이 실제로 쓰이는지, 어디서 이탈하는지, 어떤 도구는 다시 찾게 되고 어떤 도구는 한 번 보고 끝나는지가 더 선명하게 보였다.

그래서 앞으로는 무조건 개수를 늘리는 방향보다는, 반응이 좋았던 몇 개를 골라 더 깊게 다듬어보려고 한다.
결국 중요한 건 “만들었다”가 아니라 “다시 방문할 이유가 있는가”라고 생각한다.

아직은 작은 프로젝트들이지만, 직접 써보고 피드백을 받을수록 더 나아질 수 있다고 본다.
어떤 사이트가 가장 유용했는지, 어디가 불편했는지, 어떤 기능이 추가되면 좋을지 의견을 남겨주면 다음 개선에 반영해보겠다.

링크 모음

• 티켓팅 보안문자 연습
  https://ticketing-practice.lovable.app/

• Typing Speed Test
  https://typing-speed-letsgo.lovable.app/

• JSON Fixer
  https://j-fix-hero.lovable.app/

• SQL Quiz
  https://sql-guess-game.lovable.app/

• Regex Playground
  https://regex-playground-buddy.lovable.app/

• 랜덤 닉네임 생성기
  https://nickname-create.lovable.app/

• 한줄소개 생성기
  https://self-introduction-generator.lovable.app/

• Tailwind Preview
  https://tailwind-peek-studio.lovable.app/

• JSON to TypeScript 변환기
  https://swift-json-types.lovable.app/

• Dev Toolbox
  https://dev-tools-utills.lovable.app/

• Smart Calculator Hub
  https://fav-calculators.lovable.app/

• Utility Tools Hub
  https://maker-tool-spot.lovable.app/

• AI Prompt Generator
  https://promptexplorer-ai.lovable.app/

• Fun Simulator Hub
  https://fun-random-lab.lovable.app/

1. Compound Component 패턴이란?

Compound Component 패턴은 하나의 작업을 수행하기 위해 여러 개의 하위 컴포넌트들이 협력하여 하나의 단위로 동작하는 설계 방식이다.

이해한 대로 비유하자면 ‘조립식 장난감’ 같다. 부모 컴포넌트가 "넌 이렇게 생겨야 해!"라고 모든 걸 정해주는 게 아니라, 사용자가 필요한 부품(하위 컴포넌트)을 골라 원하는 위치에 끼워 맞추면서 전체 기능을 완성하는 식!

❌ 패턴 적용 전 (Props 중심)

부모 컴포넌트에 수많은 Props를 전달해야 하며, 내부 구조를 변경하기 어렵다.

<Tabs 
  items={items} 
  defaultValue="tab1" 
  onTabChange={...} 
  tabListClassName="..."
/>

✅ 패턴 적용 후 (구조 중심)

각 역할이 명확히 분리된 하위 컴포넌트를 조합할 수 있다. 직관적 미쳤음

<TabsRoot defaultValue="tab1">
  <TabsList>
    <TabsTrigger value="tab1">탭1</TabsTrigger>
  </TabsList>
  <TabsContent value="tab1">내용1</TabsContent>
</TabsRoot>

2. Compound Component와 Context API의 연관성

Compound 패턴을 만들 때 Context API는 부품들을 연결해 주는 역할을 해준다. (like 블루투스..? 무선..?)

1) 명시적인 Props 전달 제거 (Props Drilling 방지)

TabsRoot가 가진 activeTab 상태를 TabsTrigger나 TabsContent가 알기 위해서는 원래 부모를 거쳐 Props로 전달받아야 한다. 하지만 Context API를 사용하면 하위 컴포넌트들이 어디에 위치하든 상관없이 필요한 상태에 직접 접근할 수 있게 된다.

2) 유연한 레이아웃 구성

Context API 덕분에 하위 컴포넌트의 순서나 중첩 구조가 자유로워졌다. TabsList 안에 TabsTrigger를 넣든, 별도의 div로 감싸든 상관없이 Context를 통해 상태를 공유하기 때문에 UI 배치가 자유롭다.

3) 캡슐화와 사용성 향상

탭 전환 함수나 현재 활성화된 값 같은 복잡한 로직은 Context 안으로 싹 숨겨버리고(캡슐화), 사용자에게는 필요한 컴포넌트만 딱 보여줄 수 있다. 쓰는 사람 입장에서는 복잡한 계산 없이 UI를 선언적으로 툭툭 가져다 쓰기만 하면 되는!

직접 구현해 보니 Compound Component가 ‘구조적인 자유’를 준다면, Context API는 그 자유 속에서도 ‘데이터의 일관성’을 꽉 잡아주는 느낌이었다. 라이브러리 없이 순수 컴포넌트를 만들 때 이 조합은 정말 강력하고 괜찮은 선택인 것 같음!

이미지는 웹 성능에서 생각보다 큰 비중을 차지한다.

대표적인 이미지 최적화 기법

• WebP, AVIF 등 차세대 포맷으로 변환
• 디바이스 해상도에 맞는 이미지 제공
• Lazy Loading 적용 (보이는 순간에만 로드)
• Blur Placeholder로 깔끔한 로딩 연출

Next.js는 성능 향상을 위해 Image 컴포넌트를 제공한다.

즉, 단순히 <img> 대신 <Image>를 사용하기만 해도 자동으로 리사이징, 포맷 변환, Lazy Loading, CDN 캐싱이 적용된다. 이미지 최적화에는 다양한 기법이 존재한다.

import Image from 'next/image';
//...
export default function BookItem({
  id,
  title,
  subTitle,
  description,
  author,
  publisher,
  coverImgUrl,
}: BookData) {
  return (
    <Link href={`/book/${id}`} className={style.container}>
      <Image src={coverImgUrl} width={80} height={105} alt={`도서 ${title}의 표시 이미지`} />
      <div>
        <div className={style.title}>{title}</div>
        <div className={style.subTitle}>{subTitle}</div>
        <br />
        <div className={style.author}>
          {author} | {publisher}
        </div>
      </div>
    </Link>
  );
}

⚠️ Invalid src prop 오류 해결하기

Next.js의 Image는 보안상 외부 도메인의 이미지를 기본적으로 차단한다. 그래서 외부 이미지를 사용하려면 next.config.js에 허용 도메인을 명시해야 한다.

import type { NextConfig } from 'next';

const nextConfig: NextConfig = {
  logging: {
    fetches: {
      fullUrl: true,
    },
  },
  images: {
    domains: ['shopping-phinf.pstatic.net'], // 외부 이미지 도메인 등록
  },
};

export default nextConfig;

설정 후 빌드하면, Next.js가 자동으로 해당 이미지를 프록시 캐싱 및 최적화해서 제공해준다!

SEO (Search Engine Optimization) — 검색 엔진 최적화

Next.js는 SEO를 위해 metadata라는 정식 속성을 제공한다.

페이지의 제목(title), 설명(description), OG 태그(Open Graph) 등을 손쉽게 설정할 수 있음

기본 메타데이터 설정하기

검색된 약속어 metadata를 사용하여 설정을 진행하면,

export const metadata: Metadata = {
  title: '한입 북스',
  description: '한입 북스에 등록된 도서를 만나보세요.',
  openGraph: {
    title: '한입 북스',
    description: '한입 북스에 등록된 도서를 만나보세요.',
    images: ['/thumbnail.png'],
  },
};

페이지가 검색 엔진에 더 잘 노출괴도, SNS 공유 시 썸네일이 깔끔하게 표시된다.

동적인 메타 데이터 설정하기

Next.js는 정적인 메타데이터뿐만 아니라, 페이지별 데이터에 따라 동적으로 메타정보를 설정할 수 있게 해준다.

export async function generateMetadata({
  searchParams,
}: {
  searchParams: Promise<{ q?: string }>;
}) {
  // 현재 페이지의 메타 데이터를 동적으로 생성하는 역할
  const { q } = await searchParams;

  return {
    title: `${q}: 한입북스 검색`,
    description: `${q}의 검색 결과입니다.`,
    openGraph: {
      title: `${q}: 한입북스 검색`,
      description: `${q}의 검색 결과입니다.`,
      images: ['/thumbnail.png'],
    },
  };
}

export default async function Page({ searchParams }: { searchParams: Promise<{ q?: string }> }) {
  const { q } = await searchParams;

이렇게 하면 검색 결과 페이지의 쿼리(q) 값에 따라 브라우저 탭 제목, 설명, OG 메타데이터가 동적으로 변한다.

API 기반 메타데이터 생성

도서 상세 페이지의 경우, 책 정보를 API로 불러와서 그 데이터를 기반으로 SEO 메타를 생성할 수 있다. (따봉)

export async function generateMetadata({ params }: { params: Promise<{ id: string }> }) {
  const { id } = await params;

  const response = await fetch(`${process.env.NEXT_PUBLIC_API_SERVER_URL}/book/${id}`);

  if (!response.ok) {
    throw new Error(response.statusText);
  }

  const book: BookData = await response.json();

  return {
    title: `${book.title} - 한입북스`,
    description: `${book.description}`,
    openGraph: {
      title: `${book.title} - 한입북스`,
      description: `${book.description}`,
      images: [book.coverImgUrl],
    },
  };
}

export default async function Page({ params }: { params: Promise<{ id: string }> }) {
  const { id } = await params;
//...

✅ API를 메타데이터 내부에서 직접 호출해도 안전한 이유는? Request Memoization

같은 페이지 내에서 동일한 API를 여러 번 호출하더라도 자동으로 한 번만 요청하고 캐싱해주는 아름다운 친구, 덕분에 generateMetadate()와 실제 페이지 렌더링에서 같은 데이터를 불러와도 불필요한 중복 요청이 발생하지 않는다.

✅ 정리하며

https://onebite-books-page-eta-flax.vercel.app/

하나의 화면에 여러 개의 페이지 컴포넌트들를 동시에 렌더링하는 패턴

공식문서

Parallel Route는 @슬롯이름 폴더(= Slot)를 만들어 쓰고, 이 슬롯들은 부모 레이아웃의 props로 주입된다.

예를 들어 @sidebar 슬롯이 있다면 레이아웃에서는 이렇게 받는다:

export default function Layout({
  children,
  sidebar,
}: {
  children: React.ReactNode;
  sidebar: React.ReactNode;
}) {
  return (
    <div>
      {sidebar}
      {children}
    </div>
  );
}

💡 Slot은 URL에 영향을 주지 않는다. Route Group처럼 경로에는 나타나지 않고, 레이아웃에 “추가로 끼워 넣을 페이지”를 전달하는 방식으로, children은 기본 페이지 슬롯이므로 따로 폴더가 없어도 자동으로 주입된다.

이처럼 Next의 페럴렐은 여러 개의 페이지 컴포넌트를 하나의 화면에 병렬로 렌더링 시켜주는 기능이다.

Slot 안에 새로운 페이지 생성하기

parallel/@feed/setting/page.tsx

export default function Page() {
  return <div>@feed/setting</div>;
}

부모 레이아웃에서 여러 슬롯을 동시에 받으면 이렇게 적용하면 된다.

import Link from 'next/link';

export default function Layout({
  children,
  sidebar,
  feed,
}: {
  children: React.ReactNode;
  sidebar: React.ReactNode;
  feed: React.ReactNode;
}) {
  return (
    <div>
      <div>
        <Link href={'/parallel'}>parallel</Link>
        &nbsp;
        <Link href={'/parallel/setting'}>parallel/setting</Link>
      </div>
      {sidebar}
      {children}
      {feed}
    </div>
  );
}

슬롯 내의 페이지로 이동할 때 layout.tsx의 props의 값은 어떻게 될까?

슬롯 전환 시 동작 포인트!

• feed 슬롯의 경우 하위 페위지가 존재하므로 해당 UI가 렌더링된다
• sidebar 슬롯에 해당 경로의 페이지가 없으면 404가 될 수 있는데, "직전 슬롯 렌더링 결과"를 재사용해 깜빡임을 줄여준다. 이는 클라이언트 네비게이션(Link, push)에만 해당되며, 새로고침의 경우 초기 렌더링이므로 이전 결과가 없어 404가 보일 수 있다.

default.tsx

슬롯의 안전망 Slot에 매칭되는 페이지가 없을 대 보여줄 기본 UI를 제공하는 파일이다.

export default function Default() {
  return <div>/parallel/default</div>;
}

이렇게 하면 네비게이션/새로고침 상관없이 항상 슬롯 자리를 안전하게 채워준다.

Intercepting Route(인터셉팅 라우트)

"같은 경로를 가더라도, 상황에 따라 다른 UI로 가로채기" 동일한 경로에 접속하더라도 특정 조건을 만족하면, 그때는 원래 페이지가 아닌 다른 페이지를 렌더링 하도록 설정하는 기능

📌 폴더명 규칙 요약

• (.) : 동일 수준 경로의 페이지를 가로챔
• (..) : 한 단계 상위 경로 기준으로 탐색
• (..)(..) : 두 단계 상위 …
• (...) : app 바로 아래 기준

// app/(.)book/[id]/page.tsx
export default function Page() {
  return <div>가로채기 성공!</div>;
}

도서 상세를 불러오기 위해 기존에 사용하던 페이지의 컴포넌트를 import 해주고, props를 전달해준다. 이때 props는 인터셉터 과정에서 똑같이 전달되기 때문에 그대로 전달해준다.

import BookPage from '@/app/book/[id]/page';

export default function Page(props: any) {
  return (
    <div>
      가로채기 성공!
      <BookPage {...props} />
    </div>
  );
}

모달로 띄우기

'use client';

import style from '@/components/modal.module.css';
import { useRouter } from 'next/navigation';
import { useEffect, useRef } from 'react';
import { createPortal } from 'react-dom';

export default function Modal({ children }: { children: React.ReactNode }) {
  const dialogRef = useRef<HTMLDialogElement>(null);
  const router = useRouter();

  useEffect(() => {
    if (!dialogRef.current?.open) {
      dialogRef.current?.showModal();
      dialogRef.current?.scrollTo({
        top: 0,
      });
    }
  }, []);

  return createPortal(
    <dialog
      onClose={() => router.back()}
      onClick={(e) => {
        // 모달의 배경이 클릭된거면 뒤로가기
        if ((e.target as any).nodeName === 'DIALOG') {
          router.back();
        }
      }}
      ref={dialogRef}
      className={style.modal}
    >
      {children}
    </dialog>,
    document.getElementById('modal-root') as HTMLElement
  );
}

루트 레이아웃에 아래와 같이 모달 요소를 작성한다.

//...
export default function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  return (
    <html lang="en">
      <body>
        <div className={style.container}>
          <header>
            <Link href={'/'}>📚 ONEBITE BOOKS</Link>
          </header>
          <main>{children}</main>
          <Footer />
        </div>
      </body>
      <div id="modal-root"></div>
    </html>
  );
}

Intercepting & Parallel Route: @modal 슬롯

도서 리스트는 그대로 두고, 상세는 모달 슬롯으로 병렬 렌더링하기!

// app/layout.tsx
export default function RootLayout({
  children,
  modal,
}: Readonly<{
  children: React.ReactNode;
  modal: React.ReactNode;
}>) {
  return (
    <html lang="en">
      <body>
        <div className={style.container}>
          <header>
            <Link href={'/'}>📚 ONEBITE BOOKS</Link>
          </header>
          <main>{children}</main>
          <Footer />
        </div>
        {modal}
        <div id="modal-root"></div>
      </body>
    </html>
  );
}

app/@modal/(.)book/[id]/page.tsx에 작업한 도서 상세 슬롯을 옮겨서, 도서 상세 모달 뒷 배경으로 북 리스트가 보이는 메인 페이지가 보이도록 해보자.

그리고 @modal 경로에 default.tsx 페이지도 함께 만들어준다!

(.)로 book/[id]를 가로채고, 모달 슬롯에 렌더링하기

✅ 정리하며

• Parallel Route: 여러 페이지를 동시에 렌더링 (Slot은 레이아웃 props로 전달됨)
• default.tsx: 슬롯에 페이지가 없을 때 기본 UI 제공
• Intercepting Route: 같은 경로라도 클라이언트 네비게이션이면 가로채어 다른 UI(예: 모달)로 렌더링

Server Action

클라이언트에서 서버 함수를 직접 호출한다!

Server Action이란? Server Action은 브라우저에서 직접 호출할 수 있는, 서버에서만 실행되는 비동기 함수이다.

Next.js의 서버 액션은 클라이언트에서 특정 Form이 제출될 때, 그 이벤트를 서버 함수로 바로 연결해주는 기능을 제공한다. 즉, API 라우트를 따로 만들 필요 없이 단 한 줄의 자바스크립트 함수로 폼 데이터를 서버에서 처리할 수 있다.

function ReviewEditor() {
  async function createReviewAction(formData: FormData) {
    'use server';
    console.log('server action called');
  }

  return (
    <section>
      <form action={createReviewAction}>
        <input name="content" placeholder="리뷰 내용" />
        <input name="author" placeholder="작성자" />
        <button type="submit">작성하기</button>
      </form>
    </section>
  );
}

폼이 제출되면 브라우저가 서버 액션 함수를 직접 호출한다. 이떄, 입력한 값들은 자동으로 FormData 객체로 전달된다. 이 방식은 오직 자바스크립트 함수 하나만으로 쉽고 간결하게 설정할 수 있다는 강점을 갖고 있다.

서버 액션 함수를 실행할 컴포넌트에 콘솔로 어떻게 출력되는지 확인해보자.

작성하기 버튼을 클릭하면 사진과 같은 결과를 확인할 수 있다.

(1) 리뷰 추가 기능 구현하기

서버 관련 로직은 app/actions 폴더에 정리하는 게 좋다. 리뷰 추가 기능을 위한 서버 액션은 아래처럼 작성할 수 있다.👇

'use server';

export async function createReviewAction(formData: FormData) {
  const bookId = formData.get('bookId')?.toString();
  const content = formData.get('content')?.toString();
  const author = formData.get('author')?.toString();

  if (!bookId || !content || !author) {
    return;
  }

  try {
    const response = await fetch(`${process.env.NEXT_PUBLIC_API_SERVER_URL}/review`, {
      method: 'POST',
      body: JSON.stringify({ bookId, content, author }),
    });
    console.log(response.status);
  } catch (err) {
    console.error(err);
    return;
  }
}

그리고 컴포넌트에서는 이렇게 연결한다.👇

function ReviewEditor({ bookId }: { bookId: string }) {
  return (
    <section>
      <form action={createReviewAction}>
        <input name="bookId" value={bookId} hidden />
        <input required name="content" placeholder="리뷰 내용" />
        <input required name="author" placeholder="작성자" />
        <button type="submit">작성하기</button>
      </form>
    </section>
  );
}

⚠️ 참고

You provided a `value` prop to a form field without an `onChange` handler. This will render a read-only field. If the field should be mutable use `defaultValue`. Otherwise, set either `onChange` or `readOnly`.

input에 value 속성을 지정하고 onChange가 없으면 "읽기 전용" 경고가 발생한다. 이런 경우 동작에는 문제가 없지만 readonly 속성을 추가하면 해결된다.

(2) 리뷰 조회 기능 구현하기

리뷰 데이터를 가져오는 컴포넌트는 서버 컴포넌트로 작성하면 된다.

//...
async function ReviewList({ bookId }: { bookId: string }) {
  const response = await fetch(`${process.env.NEXT_PUBLIC_API_SERVER_URL}/review/book/${bookId}`);

  if (!response.ok) {
    throw new Error(`Review fetch failed : ${response.statusText}`);
  }

  const reviews: ReviewData[] = await response.json();

  return (
    <section>
      {reviews.map((review) => (
        <RevioewItem key={`review-item-${review.id}`} {...review} />
      ))}
    </section>
  );
}

(3) 서버 액션으로 페이지 재검증하기

리뷰를 작성한 뒤 새로고침하지 않아도 목록이 자동으로 갱신되도록 만들 수 있다. 이때 사용하는 함수가 바로 revalidatePath이다.

서버 액션이 실시간으로 완료되었을 떄, 사용자가 보고있는 페이지를 재검증하여 사용자 경험을 높여보자.

'use server';

import { revalidatePath } from 'next/cache';

export async function createReviewAction(formData: FormData) {
  const bookId = formData.get('bookId')?.toString();
  const content = formData.get('content')?.toString();
  const author = formData.get('author')?.toString();

  if (!bookId || !content || !author) {
    return;
  }

  try {
    const response = await fetch(`${process.env.NEXT_PUBLIC_API_SERVER_URL}/review`, {
      method: 'POST',
      body: JSON.stringify({ bookId, content, author }),
    });
    console.log(response.status);
    revalidatePath(`/book/${bookId}`);
  } catch (err) {
    console.error(err);
    return;
  }
}

revalidatePath()는 특정 경로의 페이지 캐시를 무효화하고 새로 생성한다. (=페이지 재검증) 즉, 리뷰를 등록하면 /book/[id] 페이지가 자동으로 갱신!

*PURGE: 숙청하다

⚠️ revalidatePath 메서드 주의할 점

1. 서버 액션 내부에서만 호출이 가능하다
2. 경로의 재검증을 진행하기 떄문에, 해당 경로에 있는 페이지의 모든 캐시들을 전부 다 무효화 시킨다.
3. cache: ‘force-cache’로 설정해도 무효화되어 캐시가 삭제된다.
4. 데이터 캐시뿐만 아니라 Pull Route Cache도 함께 사라진다. 즉, Pull Route Cache로써 저장되어 있던 페이지도 삭제되기 때문에, 해당 페이지에 접속하면 Next의 서버는 실시간으로 새롭게 페이지를 다시 생성하게 된다.

다양한 재검증 방식 살펴보기

revalidatePat의 옵션을 활용하여 다양한 재검증 방식을 살펴보자

태그 기반 캐시 재검증 (revalidateTag)

데이터 패칭 시 { next: { tags: ['review-1'] } } 옵션을 부여하면, 서버 액션에서 revalidateTag('review-1') 호출만으로 해당 데이터만 갱신할 수 있

// page.tsx
const response = await fetch(`${process.env.NEXT_PUBLIC_API_SERVER_URL}/review/book/${bookId}`, {
    next: { tags: [`review-${bookId}`] },
});

// create-review.tsx
'use server';

import { revalidatePath, revalidateTag } from 'next/cache';

export async function createReviewAction(formData: FormData) {
//...
  try {
    const response = await fetch(`${process.env.NEXT_PUBLIC_API_SERVER_URL}/review`, {
      method: 'POST',
      body: JSON.stringify({ bookId, content, author }),
    });

    revalidateTag(`review-${bookId}`);
  } catch (err) {
//...

이 방식은 페이지 전체를 다시 렌더링하지 않아도 되기 떄문에, 성능 면에서 훨씬 효율적이다.

클라이언트 컴포넌트에서의 서버 액션 - useActionState

클라이언트에서도 서버 액션을 제어할 수 있다. 로딩 상태나 에러 메시지를 관리할 때 유용하다.

서버는 아래와 같이 구성할 수 있다.👇

'use server';

import { revalidateTag } from 'next/cache';

export async function createReviewAction(state: any, formData: FormData) {
  const bookId = formData.get('bookId')?.toString();
  const content = formData.get('content')?.toString();
  const author = formData.get('author')?.toString();

  if (!bookId || !content || !author) {
    return {
      status: false,
      error: '리뷰 내용과 작성자를 입력해 주세요.',
    };
  }

  try {
    const response = await fetch(`${process.env.NEXT_PUBLIC_API_SERVER_URL}/review`, {
      method: 'POST',
      body: JSON.stringify({ bookId, content, author }),
    });
    if (!response.ok) {
      throw new Error(response.statusText);
    }
    revalidateTag(`review-${bookId}`);
    return {
      status: true,
      error: '',
    };
  } catch (err) {
    console.error(err);
    return {
      status: false,
      error: `리뷰 저장에 실패했습니다: ${err}`,
    };
  }
}

컴포넌트는 아래와 같이 구성할 수 있다.👇

'use client';

import { createReviewAction } from '@/actions/create-review.actions';
import style from '@/components/review-editor.module.css';
import { useActionState, useEffect } from 'react';

export default function ReviewEditor({ bookId }: { bookId: string }) {
  const [state, formAction, isPending] = useActionState(createReviewAction, null);

  useEffect(() => {
    if (state && !state.status) {
      alert(state.error);
    }
  }, [state]);

  return (
    <section>
      <form className={style.form_container} action={formAction}>
        <input name="bookId" value={bookId} hidden readOnly />
        <textarea disabled={isPending} required name="content" placeholder="리뷰 내용" />
        <div className={style.submit_container}>
          <input disabled={isPending} required name="author" placeholder="작성자" />
          <button disabled={isPending} type="submit">
            {isPending ? '...' : '작성하기'}
          </button>
        </div>
      </form>
    </section>
  );
}

(4) 리뷰 삭제 기능 구현하기

requestSubmit로 사용자가 버튼을 클릭한 것과 동일하게 동작하도록 이벤트 핸들러를 추가한다.

'use client';

import { deleteReviewAction } from '@/actions/delete-review.action';
import { useActionState, useEffect, useRef } from 'react';

export default function ReviewItemDeleteButton({
  reviewId,
  bookId,
}: {
  reviewId: number;
  bookId: number;
}) {
  const formRef = useRef<HTMLFormElement>(null);
  const [state, formAction, isPending] = useActionState(deleteReviewAction, null);

  useEffect(() => {
    if (state && !state.status) {
      alert(state.error);
    }
  }, [state]);

  return (
    <form ref={formRef} action={formAction}>
      <input name="reviewId" value={reviewId} hidden readOnly />
      <input name="bookId" value={bookId} hidden readOnly />
      {isPending ? (
        <div>...</div>
      ) : (
        <div onClick={() => formRef.current?.requestSubmit()}>삭제하기</div>
      )}
    </form>
  );
}

⚠️ 왜 submit을 사용하지 않나요? submit은 메서드 유효성 검사나 이벤트 핸들러 등을 다 무시하고 강제로 폼 제출을 발생시키기 때문에 원하지 않은 동작으로 이어질 수 있는 위험성이 있다. 이러한 문제를 예방하기 위해, 폼 유효성 검사와 이벤트를 유지한 채로 제출할 수 있는 requestSubmit 메서드를 사용한다.

 <ReviewItemDeleteButton reviewId={id} bookId={bookId} />

브라우저에서 확인하면 아래와 같다.

스트리밍이란?

데이터를 흘려보내는 기술 즉, "강물처럼 데이터를 흘려보낸다!"

스트리밍이란 말 그대로 데이터를 잘게 쪼개서 연속적으로 전달하는 기술이다. 즉, 모든 데이터를 다 받기 전에 일단 보낼 수 있는 만큼 먼저 렌더링해주는 방식!

그럼 왜 사용할까? 👉 사용자에게 빠르게 ‘뭔가’를 보여줄 수 있기 때문이다.

데이터를 기다리는 동안 아무것도 안 보이는 대신, 로딩바나 스켈레톤처럼 대체 UI를 먼저 보여주면 사용자는 "앱이 멈췄나?"라는 불안감 없이 기다릴 수 있다.

스트리밍 이전의 문제

예를 들어, 검색 페이지(/search) 같은 Dyanamic Page는 사용자가 요청할 때마다 서버가 모든 컴포넌트를 실행해서 매번 새롭게 렌더링해야 한다.

그런데 만약 특정 컴포넌트 안에서 API 요청이 오래 걸리면, 전체 페이지가 그 데이터를 기다리느라 하염없이 로딩 상태로 머물게 된다.

스트리밍 적용 후

스트리밍을 적용하면 느리게 렌더링되는 부분은 일단 대체 UI로 보여주고, 데이터가 준비되면 그 부분만 교체해서 빠르게 화면을 완성한다.

페이지 스트리밍(Page Streaming) 오래 걸리는 컴포넌트의 렌더링을 기다리는 동안, 빠르게 렌더링할 수 있는 컴포넌트들을 먼저 보여주는 기술

1. 페이지 스트리밍 적용하기

동적 페이지와 같은 폴더에 loading.tsx 파일을 만들어주면 끝!

export default function Loading() {
 return <div>Loading</div>
}

⚠️ 주의할 점

1. loading.tsx는 비동기 페이지에만 적용된다. 비동기 컴포넌트가 아니면 데이터를 불러오지 않고 있다는 의미이기 때문에, async 키워드가 있는 비동기 컴포넌트에서만 적용된다.
2. 페이지 컴포넌트 전용이다. 일반 컴포넌트 폴더 안에서는 사용할 수 없고, 대신 Suspense를 이용해야 한다.
3. Query String 변경 시엔 트리거되지 않음. 예를 들어 검색창의 쿼리만 바뀌면 전체 페이지가 로딩 상태로 가지 않는다. 그래서 페이지 전체가 한 번에 업데이트되어 UX가 살짝 어색할 수 있다.

2. 컴포넌트 스트리밍 적용하기

Suspense는 컴포넌트 단위로 스트리밍을 적용할 수 있게 해준다. 다음처럼 fallback UI를 함께 지정해주면 된다.

import BookItem from '@/components/book-item';
import { BookData } from '@/types';
import { Suspense } from 'react';

async function SearchResult({ q }: { q?: string }) {
  const response = await fetch(`{process.env.NEXT_PUBLIC_API_SERVER_URL}/book?q=${q || ''}}`, {
    cache: 'force-cache',
  });
  if (!response.ok) {
    return <div>오류가 발생했습니다...</div>;
  }

  const books: BookData[] = await response.json();

  return (
    <div>
      {books.map((book) => (
        <BookItem key={book.id} {...book} />
      ))}
    </div>
  );
}

export default async function Page({ searchParams }: { searchParams: Promise<{ q?: string }> }) {
  const { q } = await searchParams;

  return (
    <Suspense>
      <SearchResult q={q || ''} />
    </Suspense>
  );
}

이떄 key 값을 바꿔주면 Suspense가 다시 로딩 상태로 돌아간다. 검색어가 바뀔 떄마다 새로운 로딩 UI가 뜨는 이유!

//...
export default async function Page({ searchParams }: { searchParams: Promise<{ q?: string }> }) {
  const { q } = await searchParams;

  return (
    <Suspense key={q || ''} fallback={<div>Loading...</div>}>
      <SearchResult q={q || ''} />
    </Suspense>
  );
}

3. 💀 스켈레톤 UI로 사용자 경험 업그레이드

스켈레톤 = 뼈대 데이터를 불러오기 전, 페이지 구조만 먼저 보여주는 UI이다.

export default function Home() {
  return (
    <div className={style.container}>
      <section>
        <h3>지금 추천하는 도서</h3>
        <Suspense fallback={<BookListSkeleton count={3} />}>
          <RecoBooks />
        </Suspense>
      </section>
      <section>
        <h3>등록된 모든 도서</h3>
        <Suspense fallback={<BookListSkeleton count={3} />}>
          <AllBooks />
        </Suspense>
      </section>
    </div>
  );
}

로딩 중에는 이렇게 스켈레톤 컴포넌트를 보여주면 된다.👇

import BookItemSkeleton from './book-item-skeleton';

export default function BookListSkeleton({ count }: { count: number }) {
  return new Array(count)
    .fill(0)
    .map((_, idx) => <BookItemSkeleton key={`book-item-skeleton-${idx}`} />);
}

import style from '@/components/skeleton/book-item-skeleton.module.css';
export default function BookItemSkeleton() {
  return (
    <div className={style.container}>
      <div className={style.cover_img}></div>
      <div className={style.info_container}>
        <div className={style.title}></div>
        <div className={style.subTitle}></div>
        <br />
        <div className={style.author}></div>
      </div>
    </div>
  );
}

스켈레톤 UI는 사용자에게 “앱이 살아있다”는 신호를 주는 UX 기술로, 직접 구현해도 좋지만 귀찮다면 react-loading-skeleton 라이브러리를 쓰면 편하다고 하네용!

4. 에러 핸들링(error.tsx)

error.tsx 파일을 같은 경로에 만들어주면, 해당 페이지에서 발생한 에러를 전용 화면으로 처리할 수 있다. 이떄, 에러 페이지의 경우 서버 연결의 실패 등을 표현해주기 떄문에 'use client'로 설정해줘야 한다.

'use client';

export default function Error() {
  return (
    <div>
      <h3>오류가 발생했습니다.</h3>
    </div>
  );
}

추가로 error에 대해서 명시하고 싶다면, Next.js에서 제공하는 error props를 이용하면 된다.

'use client';

import { useEffect } from 'react';

export default function Error({ error }: { error: Error }) {
  useEffect(() => {
    console.error(error);
  }, []);
  return (
    <div>
      <h3>오류가 발생했습니다.</h3>
    </div>
  );
}

여기에서 Error 에는 message 라는 값이 있기 떄문에 메시지만 따로 출력할 수 있다.

Reset Props

에러 컴포넌트에서 error 이외에 추가적으로 reset이라는 props가 더 제공된다.

**reset props** 에러가 발생한 페이지를 복구하기 위해서 다시 한 번 컴포넌트들을 렌더링 시켜주는 기능을 가진 함수이다.

우리는 이걸 활용하여 다시 시도 버튼을 추가해보자!

'use client';

import { useEffect } from 'react';

export default function Error({ error, reset }: { error: Error; reset: () => void }) {
  useEffect(() => {
    console.error(error.message);
  }, []);
  return (
    <div>
      <h3>오류가 발생했습니다.</h3>
      <button onClick={() => reset()}>다시 시도</button>
    </div>
  );
}

*reset() * 클라이언트 측에서 서버에서 전달받은 데이터를 토대로 다시 렌더링하는 메서드로, 서버 컴포넌트를 다시 실행하지 않아서 데이터 페칭을 다시 불러오지는 않는다.

그러면 서버를 다시 실행시키려면 어떻게 해야할까?

--

서버 다시 실행하기

1. 브라우저를 새로고침한다.
   reset() 함수가 있는 곳에 window.location.reeload()를 대신 넣어준다. 하지만 이 방식은 오류가 발생하지 않은 곳들도 새로 가져오기 떄문에 그렇게 좋은 방식은 아니다.

2. useRouter의 refresh 메서드를 이용한다.

    'use client';
   
    import { useRouter } from 'next/navigation';
    import { useEffect } from 'react';
   
    export default function Error({ error, reset }: { error: Error; reset: () => void }) {
      const router = useRouter();
   
      useEffect(() => {
        console.error(error.message);
      }, []);
      return (
        <div>
          <h3>오류가 발생했습니다.</h3>
          <button onClick={() => router.refresh()}>다시 시도</button>
        </div>
      );
    }

   현재 페이지에 필요한 서버 컴포넌트들을 다시 불러오는 역할을 수행한다.

👉 정리하면

• router.refresh()는 서버 컴포넌트를 다시 불러오고,
• reset()은 클라이언트의 에러 상태를 리셋한다.

서버도 다시 불러오고 에러 상태인 클라이언트도 다시 리셋하자!

'use client';

import { useRouter } from 'next/navigation';
import { useEffect } from 'react';

export default function Error({ error, reset }: { error: Error; reset: () => void }) {
  const router = useRouter();

  useEffect(() => {
    console.error(error.message);
  }, []);
  return (
    <div>
      <h3>오류가 발생했습니다.</h3>
      <button
        onClick={() => {
          router.refresh();
          reset();
        }}
      >
        다시 시도
      </button>
    </div>
  );
}

⚠️ 주의할 점은 refresh() 메서드는 비동기로 실행되기 때문에, 해당 메서드의 동작이 끝난 후에 reset()을 진행해야 한다.

//...
onClick={() => {
    startTransition(() => {
        router.refresh();
        reset();
    });
}}
//...

그리고 error.tsx 파일은 하위까지 적용된다는 점 유의! (레이아웃과는 다르게 중첩되지 않고 덮어씌어짐.)

마지막으로 에러가 발생한 지점의 레이아웃까지만 렌더링을 시켜주기 때문에 위치를 잘 조정해야 한다.

라우트 세그먼트 옵션

페이지의 동작을 강제로 지정하는 옵션들

앞의 dynamicParams도 여기에 속하고, 캐싱/정적화 방식까지 페이지 성격을 딱! 정해줄 수 있다. 그 중 가장 자주 사용하는 옵션인 dynamic이라는 옵션에 대해서 살펴보자.

dynamic

특정 페이지를 static 또는 dynamic으로 “강제” 설정.

export const dynamic = 'auto' | 'force-dynamic' | 'force-static' | 'error';

• auto(기본): 아무것도 강제하지 않음. Next가 페이지 내용을 보고 자동 판정.
• force-dynamic: 매 요청마다 새로 렌더링(동적 페이지).
• force-static: 정적으로 고정(SSG처럼 캐싱). 쿼리스트링/쿠키/헤더 같은 동적 함수 쓰는 페이지에 억지로 쓰면 기능이 안 먹을 수 있음!
• error: 정적 렌더링이 불가능하면 빌드 타임에 에러를 띄워줌. (EX: Search 페이지에 error로 두면 couldn't be rendered statically 같은 에러로 잡아줌.) Search Params라는 쿼리 스트링의 값을 불러오는 동적 함수를 사용하고 있기 떄문에, Static Page로 변경할 수 없다는 오류가 발생한다.

✅ 검색/필터처럼 요청마다 데이터가 바뀌는 페이지는 auto(=동적 판단)나 force-dynamic이 안전!

클라이언트 라우터 캐시(Client Router Cache)

브라우저에 저장되는 캐시 페이지 이동을 효율적으로 진행하기 위해 페이지의 일부 데이터를 보관함

무슨 데이터가 저장될까?

RSC Payload(서버 컴포넌트 결과물) 안에는

• 루트 레이아웃
• 현재 페이지의 레이아웃
• 페이지(서버 컴포넌트 트리)

등이 모두 들어있다. Next.js는 여기서 레이아웃 부분만 뽑아서 클라이언트 라우터 캐시에 자동 저장해둔다.

그래서 어떤 이득?

이후 다른 페이지로 네이게이션할 때,

• 레이아웃은 브라우저 캐시에서 즉시 재사용
• 페이지(서버 컴포넌트) 데이터만 새로 요청하여 빠르게 진행

즉, 공통 UI(헤더/사이드바/탑바)는 재다운로드 X, 바뀌는 페이지 내용만 최소 요청으로 가져온다!

마치 캐싱된 데이터처럼 그대로 레이아웃을 사용하게 되고, 그 외에 페이지 컴포넌트나 기타 등의 서버 컴포넌트에 해당하는 데이터들은 따로 요청해서 별도로 받아오는 동작을 수행한다.

클라이언트 라우터 캐시(Client Router Cache)는 브라우저 측에 저장되는 캐시로, 한 번 방문한 페이지의 레이아웃 정보만 따로 보관해 둔다. 이후 사용자가 다른 페이지로 이동할 때, 이미 저장된 공통 레이아웃 데이터를 다시 서버에서 불러오지 않고 재사용함으로써 페이지 이동 속도를 최적화하는 기술이다. 덕분에 중복된 레이아웃을 중복으로 요청받지 않음!

실습

import { ReactNode, Suspense } from 'react';
import Searchbar from '../../components/searchbar';

export default function Layout({ children }: { children: ReactNode }) {
  return (
    <div>
      <div>{new Date().toLocaleDateString()}</div>
      <Suspense fallback={<div>Loading...</div>}>
        <Searchbar />
      </Suspense>
      {children}
    </div>
  );
}

• 라우팅으로 페이지를 왔다 갔다 해도 날짜가 안 바뀌는 걸 확인 → 이 컴포넌트가 레이아웃이라 클라이언트 라우터 캐시에 보관되어 다시 렌더링되지 않기 때문.

• 새로고침하면 날짜가 갱신 → 브라우저 캐시(클라이언트 라우터 캐시)는 새로고침/탭 종료 시 비움.

페이지 이동에는 강하고, 새로고침에는 초기화된다!

✅ 정리하며

• 레이아웃에서 “시간/랜덤값” 같은 매 순간 달라지는 값을 렌더링하면, 네비게이션 시에는 안 바뀌는 게 정상 (캐시 때문). → 페이지 컴포넌트에서 다루거나 클라이언트 컴포넌트 + 이펙트로 처리.

• 검색 페이지처럼 동적 함수(쿼리스트링/쿠키/헤더)를 쓰면 억지로 force-static 하면 동작 망가짐. auto나 force-dynamic 추천!

• 레이아웃에 클라이언트 훅(useSearchParams)을 쓸 땐 "use client" + <Suspense> 로 비동기 흐름을 안전하게 감싸기.

라우트 세그먼트 옵션으로 "페이지 성격"을 명확히 하고, 클라이언트 라우터 캐시로 "레이아웃 재사용"하면 ▶ 기깔난 App Router 네비게이션!

Full Route Cache란?

“빌드 타임에 서버가 특정 페이지의 렌더링 결과를 미리 캐싱해두는 기능”

Next.js의 서버는 페이지를 한 번 렌더링한 뒤, 그 결과물 전체를 “Full Route Cache” 라는 이름으로 저장한다.

이후 동일한 페이지의 요청이 들어오면, 다시 렌더링하지 않고 캐싱된 HTML 결과를 그래도 전달한다. 즉, 정적 페이지(SSG)의 방식과 유사하며 빠른 응답이 가능하다.

정적 페이지와 동적 페이지 구분

Next.js는 어떤 기능을 사용하느냐에 따라 자동으로 페이지를 구분한다.

Daynamic Page로 설정되는 기준

“특정 페이지가 접속 요청을 받을 떄마다 매번 변화가 생기거나, 데이터가 달라지는 경우”

다음 중 하나라도 해당되면 동적 페이지로 분류된다.

1. 캐시되지 않은 데이터 페칭을을 사용할 경우 (서버 컴포넌트에만 해당)
2. 동적 함수(쿠키, 헤더, 쿼리스트링)을 사용하는 경우

Static Page로 설정되는 기준

Dynamic Page가 아니면 모두 Static Page가 된다. (기본값)

비교해보자

Full Route Cache와 revalidate

Full Route Cache는 revalidate 옵션과 함께 사용해 ISR(Incremental Static Regeneration) 방식처럼 동작할 수도 있다.

동작 순서

1. 지정한 시간이 지나면 Next 서버는 해당 캐시를 Stale(만료됨)로 표시
2. 먼저 기존 캐시를 그대로 응답
3. 그 뒤 서버에서 새로운 데이터를 fetch
4. 렌더링 후 캐시 업데이트(Full Route Cache 최신화)

실습하며 적용!

1️⃣ useSearchParams 오류 해결

현재 useSearchParams()라는 훅은 브라우저에서만 실행 가능하기 떄문에 사전 렌더링 과정에서 빌드할 수 없다는 오류가 발생한다.

"use client";

import { useEffect, useState } from "react";
import { useRouter, useSearchParams } from "next/navigation";
import style from "./serachbar.module.css";

export default function Searchbar() {
  const router = useRouter();
  const searchParams = useSearchParams(); // 문제 발생!
  const [search, setSearch] = useState("");

이를 해결하기 위해서는 프로젝트 빌드 시 해당 파일이 빌드되지 않도록 설정해줘야 하며, 해당 컴포넌트를 사용하고 있는 부모 컴포넌트로 가서 Suspense로 해당 컴포넌트를 감싸서 렌더링 순서를 제어한다.

import { ReactNode, Suspense } from 'react';
import Searchbar from '../../components/searchbar';

export default function Layout({ children }: { children: ReactNode }) {
  return (
    <div>
      <Suspense fallback={<div>Loading...</div>}>
        <Searchbar />
      </Suspense>
      {children}
    </div>
  );
}

Suspense란?

다음 주제에서 진행되지만 미리 살펴보자

비동기 로직이 포함된 컴포넌트를 "준비될 때까지 잠시 렌더링하지 않게 해주는 장치"이다.

• fallback 속성으로 로딩 상태 UI를 지정할 수 있다.
• 여기서는 useSearchParams가 비동기 Hook이므로 Suspense가 필요하다.
  Suspense 컴포넌트로 묶여있는 컴포넌트는 미완성 상태라 곧바로 렌더링하지 않으며, 대신 fallback이라는 props로 전달한 대체 UI가 로딩 UI로서 대신 렌더링된다. (이떄, “미완성 상태”는 컴포넌트의 비동기 작업이 종료될 때까지)

  export default async function Page({ searchParams }: { searchParams: SearchParams }) {
    const { q } = await searchParams;
  
    return <div>Search Query: {q}</div>;
  }

2️⃣ 동적 경로에 적용하기

Query String을 사용하는 search 페이지처럼, 페이지 자체는 캐시 불가하지만, fetch 단위로 캐싱이 가능하다.

export default async function Page({ searchParams }: { searchParams: Promise<{ q?: string }> }) {
  const { q } = await searchParams;
  const response = await fetch(`{process.env.NEXT_PUBLIC_API_SERVER_URL}/book?q=${q || ''}}`, {
    cache: 'force-cache',
  });
  //...

3️⃣ 정적 경로 미리 생성하기

URL 파라미터를 사용하는 book/[id] 빌드 타임에 어떤 경로가 존재할지 알 수 없기 때문에 기본적으로 Dynamic Page로 처리된다.

우리는 정적 경로로 지정해야 하니, 빌드 타임에 서버에게 해당 페이지가 어떤 경로를 가질 수 있는지 미리 알려주기 위해 generateStaticParams 함수를 생성해준다.

generateStaticParams 함수는 "정적인 파라미터를 생성하는 함수"이다.

import { BookData } from '@/types';
import style from './page.module.css';

export function generateStaticParams() {
  return [{ id: '1' }, { id: '2' }, { id: '3' }, { id: '4' }, { id: '5' }];
}

export default async function Page({ params }: { params: Promise<{ id: string | string[] }> }) {
//...

반환 값으로 어떤 URL 파라미터의 어떤 페이지가 빌드 타임에 존재하는지 알려줘야 한다.

⚠️ 주의할 점

1. id는 문자열(string) 로만 지정해야 함
2. generateStaticParams를 사용한 페이지는 무조건 정적 페이지로 설정되므로, 내부의 fetch도 자동으로 정적 캐시로 동작함. (데이터 캐싱이 설정되지 않은 패칭도 정적으로 설정되니 주의!)

< 이전 빌드 결과 >

< 이후 빌드 결과 >

정적 경로 외의 페이지는 왜 렌더링될까?

generateStaticParams로 설정하지 않은 페이지도 렌더링 되는 이유는 무엇일까?

generateStaticParams로 지정하지 않은 페이지는 자동으로 Dynamic Page로 생성되어 Full Route Cache에 저장된다. 즉, 최초 접속 이후에는 캐시된 버전이 빠르게 반환된다.

🚫 지정되지 않은 경로는 Not Found로 처리하기

export const dynamicParams = false;

이 설정은 generateStaticParams에 정의된 경로 외에는 모두 404 페이지로 이동한다.

404 Not Found 페이지

요청 실패 시 모든 페이지에 노출할 공통 페이지를 만들어보자.

우선 navigation 의 notFound() 함수를 호출하여 API 로직에 아래와 같이 추가한다.

if (!response.ok) {
  if (response.status === 404) {
    notFound();
  }
  return <div>오류가 발생했습니다...</div>;
}
//...

그리고 app/not-found.tsx 파일을 추가하면 자동으로 렌더링된다.

export default function NotFound() {
  return <div>404: NotFound</div>;
}

빌드하고 재실행하여 브라우저로 접속해서 확인해보자.

✅ 정리하며

1️⃣ 앱 라우터의 데이터 페칭

기존 Page Router에서는 서버에서 데이터를 불러오기 위해 getServerSideProps, getStaticProps, getStaticPaths 와 같은 전용 함수를 사용했다.

이 함수들이 데이터를 불러오고, 그 결과를 props 형태로 컴포넌트에 전달했다.

즉, 모든 데이터가 "페이지 단위"로만 전달될 수 있었음.

⚠️ Page Router의 문제점

• 모든 컴포넌트가 클라이언트 컴포넌트로 동작함.
• 이로 인해 데이터 페칭이 서버와 브라우저에서 모두 실행되어 비효율적.
• 또한, 데이터를 최상위 페이지 컴포넌트에서만 페칭할 수 있어, 하위 컴포넌트로 넘겨주러면 props 전달 혹은 Context API를 사용해야 했음

📢 App Router의 등장

서버 컴포넌트의 등장으로 문제 해결!

App Router에서는 모든 컴포넌트가 기본적으로 서버 컴포넌트로 동작한다. 즉, 브라우저에서 실행되지 않기 때문에 async와 같은 키워드를 붙여도 문제없다.

“데이터는 필요한 곳에서 직접 불러와라” - Next.js 공식문서 (Fetching data where it’s needed)

덕분에 각 컴포넌트가 스스로 필요한 데이터를 fetch해서 렌더링할 수 있게 되었다.

실습해보자!

import BookItem from '@/components/book-item';
import books from '@/mock/books.json';
import style from './page.module.css';

export default function Home() {
  return (
    <div className={style.container}>
      <section>
        <h3>지금 추천하는 도서</h3>
        {books.map((book) => (
          <BookItem key={book.id} {...book} />
        ))}
      </section>
      <section>
        <h3>등록된 모든 도서</h3>
        {books.map((book) => (
          <BookItem key={book.id} {...book} />
        ))}
      </section>
    </div>
  );
}

데이터 페칭을 할 수 있도록 async 키워드로 비동기 함수를 만든 후 아래와 같이 작성했다.

import BookItem from '@/components/book-item';
import { BookData } from '@/types';
import style from './page.module.css';

async function AllBooks() {
  const response = await fetch(`${process.env.NEXT_PUBLIC_API_SERVER_URL}/books`);
  if (!response.ok) {
    return <div>오류가 발생했습니다...</div>;
  }

  const allBooks: BookData[] = await response.json();

  return (
    <div>
      {allBooks.map((book) => (
        <BookItem key={book.id} {...book} />
      ))}
    </div>
  );
}

async function RecoBooks() {
  const response = await fetch(`${process.env.NEXT_PUBLIC_API_SERVER_URL}/books/random`);
  if (!response.ok) {
    return <div>오류가 발생했습니다...</div>;
  }

  const randomBooks: BookData[] = await response.json();

  return (
    <div>
      {randomBooks.map((book) => (
        <BookItem key={book.id} {...book} />
      ))}
    </div>
  );
}

export default function Home() {
  return (
    <div className={style.container}>
      <section>
        <h3>지금 추천하는 도서</h3>
        <RecoBooks />
      </section>
      <section>
        <h3>등록된 모든 도서</h3>
        <AllBooks />
      </section>
    </div>
  );
}

3️⃣ 데이터 캐시 (Data Cache)

Next.js는 fetch() 결과를 서버 측에서 자동으로 캐싱할 수 있도록 만들었다. 이 덕분에 동일한 요청이 반복될 때, 데이터를 어떤 방식으로 캐싱할지 지정할 수 있다.

• 영구적으로 데이터를 보관
• 혹은 특정 시간을 주기로 데이터 갱신

등의 기능을 수행하며, 사용 방법은 아래와 같다.

const response = await fetch(`/api`, { cache: "force-cache" });

Cache 옵션

{ cache: "no-store" }

• 데이터 페칭의 결과를 아예 캐싱하지 않도록 설정하는 옵션
• 기본값으로 지정되는 옵션이다.

새로고침 후 콘솔에서 확인해보면cache skip으로 출력됨을 확인할 수 있다.

{ cache: "force-cache" }

• 요청의 결과를 무조건 캐싱하며, 한 번 호출된 이후에는 다시 호출되지 않는다.

새로고침 후. 콘솔로 확인해보면 cache hit 즉, 캐싱된 데이터를 찾는다는 것을 알 수 있다.

{ next: { revalidate: 3 } }

• 특정 시간을 주기로 캐시를 업데이트 하며, 마치 Page Router의 ISR 방식과 유사하다.

실행 후, 지정한 시간을 주기로 새로고침 되는 것을 확인할 수 있다.

{ next: { tags: ['a'] } }

• 요청이 들어왔을 때 데이터를 최신화한다.(On-Demand Revalidate)

추가로 데이터 페칭이 발생할 때마다 로그를 출력하는 설정은 아래와 같다.

import type { NextConfig } from 'next';
>
const nextConfig: NextConfig = {
  logging: {
    fetches: {
      fullUrl: true,
    },
  },
};
>
export default nextConfig;

3. Request Memoization

“요청을 기억한다.” — 동일한 요청을 자동으로 한 번만 수행하도록 최적화하는 기능이다.

서버 컴포넌트 구조상, 여러 컴포넌트가 같은 데이터를 요청할 수 있다. (ex. 각 서버 컴포넌트들이 자신들이 필요한 데이터를 알아서 불러오기 때문!) 이때 Next.js는 동일한 요청을 하나로 묶어 처리하고, 결과를 공유한다.

데이터 캐시 vs 리퀘스트 메모이제이션

App Router의 네비게이팅

1️⃣ 페이지 이동의 기본 개념

Next.js의 페이지 이동은 Page Router 시절과 동일하게 CSR(Client Side Rendering) 방식으로 이루어진다. 즉, 한 번 페이지를 로드한 이후에는 브라우저 내에서 페이지 전환이 일어나며, 전체 새로고침 없이 부드럽게 이동한다.

하지만! App Router에서는 "서버 컴포넌트(Server Component)"라는 개념이 추가되면서, Page Router 때와는 조금 다른 흐름이 생겼다.

2️⃣ App Router에서의 동작 방식

Page Router에서는 사용자가 페이지를 처음 방문하면, 서버가 JS Bundle(자바스크립트 묶음 파일) 을 보내준다.

그래서 만약 브라우저가 JS Bundle만 받게 된다면, 서버에서 렌더링된 내용(즉, 데이터)은 통째로 빠져버리게 된다.

JS Bundle에는 컴포넌트만 포함되어 있기 떄문!

이를 방지하기 위해서 Next.js는 JS Bundle과 함꼐 서버 컴포넌트의 결과물인 RSC Payload도 함께 전달한다.

즉, App Router의 페이지 이동은 JS Bundle + RSC Payload = 완성!으로, 이 두 가지가 함께 있어야 완전한 페이지가 구성된다.

3️⃣ 실습: 네비게이션바 구성하기

공통 네비게이션을 위해 Root Layout에 header 요소를 추가하고 실행해보자.

어떤 페이지로 이동하든 헤더가 고정된 채로 RSC Payload가 함께 전달되는 걸 확인할 수 있다.

특히 검색 페이지(/search)에 들어가면 RSC Payload만 전달되고 JS Bundle은 없는 걸 볼 수 있는데, 이건 /search 페이지는 순수한 서버 컴포넌트로 구성되어 있기 떄문이다. (= 서버 컴포넌트로만 이루어져 있어서 클라이언트 컴포넌트를 전달하지 않는다.)

App Router에서 페이지 이동은 Page Router 버전의 페이지 이동과 거의 동일하지만, Server Component의 추가로

• Response에 서버 컴포넌트는 RSC Payload로
• 클라이언트 컴포넌트는 기존의 JS Bundle로 전달되는
  차이점을 기억하면 된다.

4️⃣ App Router의 페이지 이동

App Router의 페이지 이동은 기존 CSR과 동일하지만, 서버 컴포넌트의 결과물이 추가로 포함된다!

함수로 페이지 이동하기

'next/navigation'의 useRouter를 사용하면, 클라이언트 컴포넌트에서 페이지 이동을 쉽게 제어할 수 있다.

'use client';

import { useRouter } from 'next/navigation';
import React, { useState } from 'react';

export default function Searchbar() {
  const router = useRouter();
  const [search, setSearch] = useState('');

  const onChangeSearch = (e: React.ChangeEvent<HTMLInputElement>) => {
    setSearch(e.target.value);
  };

  const onSubmit = () => {
    router.push(`/search?q=${search}`);
  };

  return (
    <div>
      <input value={search} onChange={onChangeSearch} />
      <button onClick={onSubmit}>검색</button>
    </div>
  );
}

버튼을 누를 때 router.push()로 이동하는 방식은 기존 next/router의 useRouter와 거의 동일하다!

5️⃣ 정적 페이지와 동적 페이지의 응답 차이

App Router의 모든 페이지는 Static(정적) 또는 Dynamic(동적) 페이지로 분류된다.

Static 페이지는 Page Router 버전으로 SSG 방식. Dynamic 페이지는 Page Router 버전으로 SSR 방식! 다시 기억하기

차이점 1. 음답 내용

정적 페이지

• RSC Payload + JS Bundle
• 프리패칭으로 빠르게 불러옴

동적 페이지

• RSC Payload만 응답
• JS Bundle은 데이터 변경 시점에서 로드됨

차이점 2. 빌드 결과 확인

npm run build를 실행하면, Next.js가 어떤 페이지가 정적/동적인지 표시해준다.

URL 파라미터를 사용하는 /book/[id]와 Query String을 사용하는 /search 는 동적 페이지로 설정된 걸 확인할 수 있다.

이처럼 분류된 이유는, Queryn String이나 URL 파라미터를 꺼내는 등 빌드 타임에 생성하면 안 될 것 같은 동작을 수행하는 경우는 동적인 페이지(Dynamic 페이지)로 설정되기 떄문이다.

✅ 정리하며

• App Router의 페이지 이동은 CSR 기반이다.
• 클라이언트 컴포넌트는 JS Bundle + RSC Payload가 함께 전달된다.
• App Router에서 페이지의 데이터는 서버 컴포넌트 RSC Payload로 전달된다.
• 순수 서버 컴포넌트 페이지는 JS Bundle이 없다.
• Query String 또는 URL Param을 사용하면 Dynamic 페이지로 분류된다.

• 정적(Static) 페이지의 경우 데이터의 업데이트가 필요하지 않으니 프리패칭으로 RSC Payload와 JS Bundle을 둘 다 불러오고,

• 동적(Dynamic) 페이지의 경우, 데이터의 업데이트가 필요할 수 있기 때문에 RSC Payload만 불러온다. JS Bundle의 경우 데이터 업데이트가 발생한 순간에 불러오게 된다.

1. 리액트 서버 컴포넌트 이해하기

1️⃣ 리액트 서버 컴포넌트란?

React Server Component(RSC) 서버에서만 실행되는 컴포넌트로, 브라우저에서는 전혀 실행되지 않는다.

• 즉, 서버 컴포넌트는 서버에서 HTML을 사전 렌더링할 때 딱 한 번만 실행되고, 브라우저에서는 이미 만들어진 HTML만 전달받는다.
• 반면, 클라이언트 컴포넌트는 사전 렌더링 때 한 번, 하이드레이션 때 한 번, 총 두 번 실행된다.

2️⃣ 서버 vs 클라이언트

Next.js의 App Router에서는 기본적으로 모든 컴포넌트가 서버 컴포넌트(Server Component)이다.

즉, 기본값은 서버 컴포넌트!

클라이언트 컴포넌트를 사용하고 싶다면, 컴포넌트 파일의 최상단에 'use client'를 선언해주면 된다.

'use client';
import { useEffect } from 'react';
import styles from './page.module.css';

export default function Home() {
  useEffect(() => {}, []);
  return <div className={styles.page}>인덱스 페이지</div>;
}

3️⃣ 클라이언트 컴포넌트는 언제 써야 할까?

브라우저에서만 가능한 동작이 있다면 클라이언트 컴포넌트로 만든다.

• React의 Hook(useState, useEffect) 같은 것들은 브라우저 환경에서만 동작하는 것
• 또는 사용자의 입력, 클릭, 드래그 등과 같은 “상호작용(interaction)”이 필요한 부분

권장사항

• 페이지의 대부분을 서버 컴포넌트로 구성할 것
• 클라이언트 컴포넌트는 꼭 필요한 경우에만 사용할 것

구체적으로 구분하자면, “상호작용이 있어야 하면” 클라이언트 컴포넌트로 만들고 그렇지 않다면 서버 컴포넌트로 만들면 된다.

4️⃣ 검색창 만들기

검색창은 사용자가 검색어를 입력하면 state가 변하기 떄문에 대표적인 클라이언트 컴포넌트이다.

'use client';

import React, { useState } from 'react';

export default function Searchbar() {
  const [search, setSearch] = useState('');

  const onChangeSearch = (e: React.ChangeEvent<HTMLInputElement>) => {
    setSearch(e.target.value);
  };

  return (
    <div>
      <input value={search} onChange={onChangeSearch} />
      <button>검색</button>
    </div>
  );
}

이렇게 'use client'를 선언하면 Next.js가 해당 파일을 브라우저용으로 번들링해서 클라이언트에서 동작하도록 만들어준다.

5️⃣ Co-Location

컴포넌트를 어디에 둬야 할까?

App Router에서는 page.tsx, layout.tsx처럼 특별한 예약 파일명을 제외하면 그 외의 파일은 일반적인 JS/TS 파일로 간주한다. 그래서 app 폴더 안에서도 자유롭게 컴포넌트를 만들어둘 수 있다.

이러한 패턴을 Co-Location이라고 부른다.

즉, 페이지와 관련된 컴포넌트를 같은 위치에 함께 배치할 수 있다는 뜻이다! (ex. app/(with-searchbar)/search/components/Searchbar.tsx 등) 이러한 구조 덕분에 관련된 코드끼리 관리할 수 있어서 코드 가독성과 유지보수성에 도움이 된다.

2. 리액트 서버 컴포넌트 주의 사항

1️⃣ 서버 컴포넌트에는 브라우저에서 실행될 코드가 포함되면 안된다.

서버 컴포넌트는 이름 그대로 서버에서만 실행된다. 그래서 아래와 같은 브라우저 전용 코드들은 포함될 수 없음!

• 브라우저에서만 동작하는 React Hook(useState, useEffect 등)
• 클릭, 입력 같은 이벤트 핸들러
• 브라우저 전용 라이브러리 (예: DOM 조작 라이브러리)

이런 코드는 반드시 'use client'를 선언한 클라이언트 컴포넌트 안에서만 사용해야 한다.

서버 컴포넌트는 **"렌더링 결과만 반환하는 순수한 UI 정의 영역"

2️⃣ 클라이언트 컴포넌트는 클라이언트에서만 실행되지 않는다.

클라이언트 컴포넌트는 서버에서 한 번, 클라이언트에서 한 번, 총 두 번 실행된다.

즉, 서버와 브라우저 양쪽에서도 실행된다!

3️⃣ 클라이언트 컴포넌트에서 서버 컴포넌를 import 하면 안 된다.

클라이언트 컴포넌트는 앞서 말했듯 서버와 브라우저 모두에서 실행된다. 그런데 이 컴포넌트 안에서 서버 컴포넌트를 import 하게 되면 어떻게 될까?

❌ 브라우저에서도 서버 컴포넌트를 실행하려 하기 때문에 "런타입 에러"가 발생한다.

Next.js는 이런 경우를 해결하기 위해, 서버 컴포넌트를 자동으로 클라이언트 컴포넌트로 변환해버린다. 하지만 이건 일시적인 해결책으로 좋은 해결 방식은 아니다.

💡 권장 방식 클라이언트 컴포넌트에서 서버 컴포넌트를 직접 import 하지 말고, props로 ReactNode 타입의 children을 받아 렌더링하는 방식을 사용한다.

이 방식을 사용하면 서버 컴포넌트가 클라이언트 컴포넌트 안에서도 안전하게 렌더링된다.

4️⃣ 서버 컴포넌트에서 클라이언트 컴포넌트에게 "직렬화 불가능한 Props"를 전달하면 안된다.

서버 컴포넌트는 렌더링 결과를 직렬화(serialize)해서 클라이언트로 전달한다. 즉, 데이터는 문자열(JSON 형태)로 변환되어야 클라이언트 컴포넌트로 전달된다.

그런데 만약 직렬화 불가능한 데이터를 props로 전달한다면?

• 함수
• 클래스 인스턴스
• Symbol
• 복잡한 클로저나 참조 타입

❌ Error: A function cannot be passed to a Client Component from a Server Component. 즉, 서버에서 "브라우저가 이해할 수 없는 형태의 데이터"를 넘기려 하면 에러가 발생한다.

import ClientComponent from './ClientComponent';

export default function ServerComponent() {
  const handleClick = () => alert('Click!'); // ❌ 함수는 직렬화 불가
  return <ClientComponent onClick={handleClick} />;
}

함수는 브라우저로 보낼 수 없기 때문에 에러가 발생한다.

✅ 해결 방법 브라우저에서 실행되어야 하는 로직이라면, 클라이언트 컴포넌트 내부에서 직접 정의애햐 한다.

'use client';
export default function ClientComponent() {
  const handleClick = () => alert('클라이언트에서 실행!');
  return <button onClick={handleClick}>클릭</button>;
}

💡RSC Payload란?

React Server Component의 순수한 결과물로, "서버 컴포넌트를 직렬화한 데이터 덩어리"로 볼 수 있다.

RSC Payload에는 서버 컴포넌트의 모든 데이터가 포함된다.

1. 서버 컴포넌트의 렌더링 결과
   • 서버에서 사전 렌더링된 HTML 정보
2. 연결된 클라이언트 컴포넌트의 위치
   • 어디에 어떤 클라이언트 컴포넌트가 들어갈지에 대한 매핑 정보
3. 클라이언트 컴포넌트로 전달할 Props 값
   • 상호작용을 위해 필요한 props 데이터

즉, 서버는 RSC Payload를 만들어 브라우저에게 보내고, 브라우저는 그골 벋어 하이드레이션을 진행하며, "서버 + 클라이언트가 연결된 완전한 페이지"를 구성하는 것이다.

1️⃣ 프로젝트 생성하기

먼저 아래 명령어로 새로운 Next.js 프로젝트를 만들어준다.

npx create-next-app@latest section03

설치 중에 나오는 질문 중

Would you like to use App Router?

👉 Yes 를 선택!

App Router를 사용하면, 기존에 있던 pages 폴더가 사라지고 app 폴더 구조로 전환된다.

✅ App Router는 Next.js 13부터 새롭게 도입된 방식으로, 서버 컴포넌트 기반의 훨씬 유연한 구조를 제공한다.

2️⃣ 페이지 라우팅 설정하기

App Router에서 페이지 라우팅은 어떻게 다를까?

기존 Page Router에서는 index.tsx를 만들어 페이지를 구성했지만, 이제는 파일 이름이 page.tsx 로 바뀌었다. 즉, 경로마다 page.tsx 파일을 만들어주면 그게 바로 “페이지”가 된다.

App Router에서는 Query String이나 URL 파라미터 같이 경로 상에 포함되는 값은 page.tsx 컴포넌트의 props로 전달된다는 것을 기억하며 살펴보자!

(1) URL 파라미터 설정하기

예전처럼 [id].tsx 파일을 만들지 않고, 이제는 [id]라는 폴더를 생성한 후, 그 안에 page.tsx를 만들어야 한다.

export default function Page() {
  return <div>book/[id] page 입니다</div>;
}

실행하면 아래와 같은 결과를 확인할 수 있다.

URL 파라미터 값을 꺼내서 사용해보자!

export default async function Page({ params }: { params: { id: string } }) {
  const { id } = params;
  return <div>book/[id] page: {id}</div>;
}

✅ 정리하며

• params는 URL 경로의 파라미터 값을 Promise 형태로 전달해준다.
• 세그먼트(...id)도 동일하게 사용할 수 있지만, 경로가 없을 수도 있다면 [[...id]] 로 설정해주는 게 안전하다.

(2) Query String 설정하기

props를 콘솔로 출력해보면, params: Promise {...}, searchParams: Promise {...} 의 객체 형태의 값을 확인할 수 있다.

export default async function Page({ searchParams }: { searchParams: { q: string } }) {
  const { q } = searchParams;
  return <div>검색 페이지: {q}</div>;
}

참고로 함수형 컴포넌트에 async를 붙일 수 있는 이유는, App Router의 컴포넌트가 서버 컴포넌트(Server Component) 로 동작하기 때문!

3️⃣ 레이아웃 설정하기

App Router는 페이지마다 반복되는 UI를 효율적으로 관리할 수 있다.

(1) 공통된 경로의 레이아웃 만들기

특정 경로에 공통된 UI를 적용하려면, 해당 폴더에 layout.tsx 파일을 추가하면 된다.

export default function Layuout({ children }: { children: React.ReactNode }) {
  return (
    <div>
      <div>임시 서치바</div>
      {children}
    </div>
  );
}

layout.tsx → page.tsx 순으로 실행되며, 하위 경로에도 자동으로 적용됨.

하위 폴더(setting)에도 layout.tsx를 추가하면, 두 개의 레이아웃이 중첩 적용된다.

export default function Page() {
  return <div>search/setting</div>;
}

export default function Layout({ children }: { children: React.ReactNode }) {
  return (
    <div>
      <div>세팅 헤더</div>
      {children}
    </div>
  );
}

중첩 레이아웃까지 적용된 것을 확인할 수 있다.

• ⚠️ 루트의 layout.tsx는 절대 삭제하면 안 된다.(앱 전체의 기본 구조를 담당)

(2) 공통된 경로가 아닌 페이지끼리 레이아웃 공유하기

이번엔 서로 다른 경로지만 공통 레이아웃을 적용하고 싶을 때! 이럴 땐 Route Group 기능을 사용한다.

(폴더명) 형태로 작성하면, 해당 폴더는 실제 URL 경로에는 포함되지 않음 👇

• 경로에 영향을 주지 않기 떄문에 경로가 정상적으로 작동한다.
• 공통 레이아웃이 필요한 페이지들을 생성한 폴더에 넣은 후, 레이아웃을 설정할 수 있다.
  

실행 후 확인해보자! 👇

경로가 달라도 공통 레이아웃이 잘 적용됨! (Route Group 덕분에 경로는 깔끔하게, 구조는 유연하게 유지~)

✅ 정리하며

• App Router는 page.tsx와 layout.tsx로 구성
• URL 파라미터는 params, 쿼리 스트링은 searchParams로 접근
• 레이아웃은 폴더 구조 기반으로 자동 적용
• Route Group으로 경로에 영향 없이 공통 UI 관리 가능

1. 기본 특징

• Page Router는 파일 시스템 기반 라우팅을 제공하여 pages 폴더 안에 파일을 생성하면 자동으로 라우팅됨.
  • 예: pages/index.tsx → /
  • pages/search.tsx → /search
  • pages/book/[id].tsx → /book/:id
• 장점
  • 별도의 라우팅 코드가 거의 필요 없음.
  • 폴더 구조만으로 라우팅을 자유롭게 설정 가능.
  • URL 파라미터와 다이나믹 라우팅(.id)도 쉽게 지원.

2. 사전 렌더링 방식

Page Router는 두 가지 사전 렌더링 방식을 제공:

1. SSR (Server-Side Rendering)
   • 매 요청마다 서버에서 HTML을 새로 생성.
   • 항상 최신 데이터를 보장하지만 응답 속도가 느려질 수 있음.
2. SSG (Static Site Generation)
   • 빌드 시점에 HTML을 미리 생성.
   • 빠른 응답 가능, 그러나 최신 데이터 반영 어려움.
3. ISR (Incremental Static Regeneration)
   • SSG 페이지를 일정 시간마다 갱신하거나 on-demand로 재생성 가능.
   • 최신성과 속도를 동시에 어느 정도 만족시킴.

3. 단점

• 레이아웃 설정의 불편함
  • 페이지별 레이아웃을 설정하려면 getLayout 같은 패턴을 직접 구현해야 함.
  • 코드 중복과 복잡성이 생기기 쉬움.
• 데이터 패칭 제약
  • getServerSideProps, getStaticProps 등 특수 함수 사용 필요.
  • 데이터 전달 구조가 props 기반이라 중첩 컴포넌트까지 데이터 전달 시 복잡해짐.
• 불필요한 컴포넌트 렌더링 문제(= 불필요한 컴포넌트들도 JS Bundle에 포함된다)
  • 서버 사이드 렌더링 시 모든 컴포넌트가 한 번에 실행.
  • 상호작용(인터랙션)이 필요 없는 단순 렌더링 컴포넌트도 불필요하게 포함되어 성능 저하 유발.
  • 이로 인해 hydration 단계에서 브라우저에서 한 번 더 실행되어 비효율적.

4. 정리

• Page Router는 간단하고 직관적인 파일 기반 라우팅을 제공하며,

  SSR, SSG, ISR 세 가지 렌더링 방식을 지원하여 다양한 케이스에 대응 가능.

• 그러나 레이아웃 관리, 데이터 전달 구조의 한계, 불필요한 렌더링 등의 단점이 존재.

• 이 한계들을 보완하기 위해 App Router가 새롭게 등장.

SEO 설정하기

1. 기본 SEO 설정

Next.js에서는 next/head에서 제공하는 Head 컴포넌트를 불러와서 SEO 설정을 해줄 수. 있다.

import Head from 'next/head';

export default function Home({ allBooks, randomBooks }) {
  return (
    <Head>
      {/* 페이지 이름 */}
      <title>한입북스</title>

      {/* 오픈 그래프 태그 */}
      {/* 썸네일 이미지는 public 폴더 기준 경로 */}
      <meta property="og:image" content="/thumbnail.png" />

      {/* 타이틀 */}
      <meta property="og:title" content="한입북스" />

      {/* 설명 */}
      <meta property="og:description" content="한입북스에 등록된 도서들을 만나보세요" />
    </Head>
  );
}

✅ 요약하면,

• <title> : 페이지 제목
• <meta property="og:image"> : 미리보기 썸네일
• <meta property="og:title"> : 공유될 때 보여줄 제목
• <meta property="og:description"> : 공유될 때 보여줄 설명

이렇게만 넣어도 기본적인 SEO는 끝!

2. 상세 페이지에 SEO 반영하기

상세 페이지도 마찬가지다. 다만 책 데이터마다 내용이 다르니 동적으로 바꿔주는게 제일 좋다!

import { useRouter } from 'next/router';

export default function Page({ book }) {
  const router = useRouter();
  if (router.isFallback) return '로딩 중입니다...';

  const { title, description, coverImgUrl } = book;

  return (
    <Head>
      <title>{title}</title>
      <meta property="og:image" content={coverImgUrl} />
      <meta property="og:title" content={title} />
      <meta property="og:description" content={description} />
    </Head>
  );
}

이렇게 하면 서버에서 받아온 데이터로, 책에 맞는 메타태그가 적용됨!

⚠️ 주의할 점: SEO가 반영되지 않는 단점

SSG(동적 경로) + fallback: true 옵션을 사용했을 때는 빌드 타임에 페이지가 미리 만들어지지 않아서, 페이지에 처음 접근하면 SEO 메타 태그가 누락될 수 있다.

즉, 페이지 처음 요청 시엔 "로딩 중입니다..." 같은 상태만 보이고, 메타태그가 적용되지 않음.

이럴 땐 isFallback 상태일 때도 기본 메타태그를 넣어주면 된다.

if (router.isFallback) {
  return (
    <>
      <Head>
        <title>한입북스</title>
        <meta property="og:image" content="/thumbnail.png" />
        <meta property="og:title" content="한입북스" />
        <meta property="og:description" content="한입북스에 등록된 도서들을 만나보세요" />
      </Head>
      <div>로딩중입니다...</div>
    </>
  );
}

이렇게 하면 로딩 상태일 때도 기본적인 SEO가 유지된다.

✅ 정리하며

• next/head를 이용해 <title>과 <meta> 태그로 기본적인 SEO 설정 가능
• 오픈 그래프 태그(og:image, og:title, og:description) 활용하면 SNS 공유시 예쁘게 뜸
• fallback: true일 때는 SEO가 빠질 수 있으므로 isFallback 조건 처리로 보완

SEO도 "페이지를 어떻게 보여줄까?"를 제어하는 거라, 로딩 상태까지 처리해줘야 한다는 사실!을 처음 알았네요...

ISR(Incremental Static Regeneration)

ISR이란?

ISR(증분 정적 재생성)은 간단히 말해 SSG 방식으로 생성된 정적 페이지를 일정 시간 주기로 다시 생성하는 기술이다.

즉, SSG처럼 미리 만들어진 페이지를 빠르게 응답해주면서, 주기적으로 새로운 데이터를 반영할 수 있는 것으로, 👉 SSG의 장점(빠른 속도) + SSR의 장점(최신 데이터 반영)까지 합친 방식!

ISR 동작 흐름

이미지 기준으로

• 빌드 타임(0초): 기존 페이지(V1) 생성
• 60초 이후: 브라우저 요청이 들어오면 새로운 페이지(V2) 재생성
• 이후 요청부터는 최신 버전(V2) 응답

✅ 이미 만들어둔 페이지를 전달해주니 속도는 빠르고, 일정 주기마다 업데이트가 되니까 데이터도 최신으로 유지할 수 있다!

실습 코드

export const getStaticProps = async () => {
  const [allBooks, randomBooks] = await Promise.all([
    fetchBooks(),
    fetchRandomBooks()
  ]);
  return {
    props: {
      allBooks,
      randomBooks,
    },
    revalidate: 3,
  };
};

여기에서 revalidate: 3을 추가, 이 값은 재생성할 주기(초 단위)를 의미한다.

빌드 후 로그를 보면,

ISR: 3 Seconds

3s마다 새롭게 데이터를 가져와 페이지를 업데이트한다는 뜻으로, 실제 실행 후 3초 주기로 새로고침하면 리스트 데이터가 달라지는 걸 확인할 수 있다.

주문형 재검증(On-Demand ISR)

하지만 위처럼 모든 페이지가 시간 단위로만 갱신되면 불편한 경우가 있다.

🥹: 사용하즤 특정 행동(데이터 수정, 글 작성 등)에 맞춰서 즉시 업데이트가 필요할 때는 어떻게 하나요? 😎: 이때 사용하는 게 On-Demand ISR입니다.

브라우저 요청마다 페이지를 다시 생성하는 SSR은 부담이 크니, 개발자가 직접 트리거(Trigget)를 걸어 주는 방식이다.

ISR 방식 구분하기

• 시간 기반 ISR: 일정 시간마다 자동 업데이트
• 요청 기반 ISR: 필요할 때마다 직접 페이지 재생성

실습 코드

import { NextApiRequest, NextApiResponse } from 'next';

export default async function handler(req: NextApiRequest, res: NextApiResponse) {
  try {
    await res.revalidate('/'); 
    return res.json({ revalidate: true });
  } catch (error) {
    console.error(error);
    res.status(500).send('Revalidation Failed');
  }
}

여기서 핵심은 res.revalidate() 함수이다. 이 함수는 인수로 "어떤 경로를 revalidate 할지 지정해주면 된다. 예시에서는 / 경로를 갱신하도록 진행!

✅ 정리하며

• ISR = 정적 페이지 + 최신성 보장
• revalidate 옵션으로 일정 주기마다 페이지를 재생성
• 필요할 때는 On-Demand ISR로 개발자가 직접 트리거 가능!!

빠르면서도 최신 데이터를 유지하는 방식이다.

1. SSG란?

정적 사이트 생성(SSG)은 SSR의 단점을 보완하는 사전 렌더링 방식이다. 즉, 빌드 타임에 페이지를 미리 생성해두는 것!!

서버가 실행되기 전에 모든 페이지를 미리 만들어두는 방식이라, 사용자가 접속하면 서버는 그냥 미리 준비된 HTML을 "빠르게" 전달해준다. 이 방식은 빌드 시간이 오래 걸려도 개발자만 겪는 고통이라, 사용자 입장에서는 항상 빠르게 응답받을 수 있다.

SSG의 장점 & 단점

장점

• 빠른 속도: 페이지를 미리 만들어두니 요청 즉시 응답이 가능하다.
• 안정성: 매번 서버 연산이 없어도 동일한 결과를 제공한다

단점

데이터 최신화가 어렵다.

• 빌드 이후에는 페이지가 고정돼버려서, 새로운 요청이 와도 항상 같은 응답만 전달된다.
• 문제가 되는건 아니지만, 최신 데이터를 반영하기 힘들다는게 아쉬운 점!

2. SSG 적용해보기

이전 게시글에서 다룬 getServerSideProps와 동일한 방식으로, SSG 전용 함수인 getStaticProps와 getStaticPaths를 사용하면 된다.

getStaticProps

빌드 타임에 필요한 데이터를 미리 불러와 페이지에 props로 전달해준다.

//...
import { InferGetServerSidePropsType } from 'next';
import { ReactNode } from 'react';

export const getStaticProps = async () => {
  const [allBooks, randomBooks] = await Promise.all([fetchBooks(), fetchRandomBooks()]);
  return {
    props: {
      allBooks,
      randomBooks,
    },
  };
};

export default function Home({
  allBooks,
  randomBooks,
}: InferGetStaticPropsType<typeof getStaticProps>) {
//...

여기에서 InferGetStaticPropsType의 역할은 InferGetServerSidePropsType와 동일하게 자동으로 타입을 추론해서 설정해준다.

빌드 타임에 딱 한 번 실행되는지 확인하기

export const getStaticProps = async () => {
  console.log('인덱스 페이지');
  const [allBooks, randomBooks] = await Promise.all([fetchBooks(), fetchRandomBooks()]);
  return {
    props: {
      allBooks,
      randomBooks,
    },
  };
};

해당 페이지를 새로고침 하면, 새로고침 할때마다 콘솔에 작성한 내용이 출력된다.

😎: 어라 한 번만 실행되야 하는거 아닌가요? ✍️: 개발 모드로 실행할 때는 수정 결과가 바로 반영되기 때문에, 렌더링 방식이 달라도 요청이 달라도 계속 사전 렌더링을 진행합니당! 그러니 Production(npm run build)로 실행해야 해용!

SSG 설정을 적용한 뒤 npm run build를 실행하여 콘솔 확인해보기

• Generating static pages 👉 getStaticProps를 사용한 페이지들이 실제 정적 파일로 생성되는 걸 확인할 수 있음.
• 이때 “인덱스 페이지” 같은 콘솔 메시지가 보였다면, 작성했던 함수(getStaticProps)가 빌드 타임에 실행된 게 맞다는 증거!

● ○ f 심볼의 의미

빌드 로그 맨 아래를 보면 페이지마다 ●, ○, f 표시가 붙어 있는데, 이건 해당 페이지가 어떤 방식으로 사전 렌더링되었는지 알려주는 표식이다.

● (Static)

• 그냥 정적 페이지. getStaticProps 없이도 기본적으로 제공되는 정적 페이지.

○ (SSG)

• getStaticProps를 사용해 SSG로 생성된 페이지.
• 빌드 타임에 데이터 패칭까지 끝내고 정적으로 만들어진 페이지.

ƒ (Dynamic)

• 동적으로 서버 사이드 렌더링(SSR)되는 페이지.
• 주문형(On demand)으로, 브라우저 요청이 들어올 때마다 페이지가 새로 사전 렌더링 됨.

---

API Routes의 기본 동작

여기에서 API Routes는 자동으로 SSG 동작한다. 즉, API 라우트에 대해서는 매 요청마다 서버에서 새롭게 실행된다는 점!

---

Production 모드에서 확인하기 🚀

npm run build 후 npm run start로 production 모드를 실행하면, SSG, SSR로 설정한 기본 정적 페이지들이 각각 어떤 방식으로 동작하는지 브라우저에서 직접 확인할 수 있다.

🚨 SSG에서 Query String은 왜 못 쓸까?

• Query String(?q=검색어)이라는 건 브라우저가 요청을 보낼 때 URL에 붙여서 전달하는 값
• 그런데 SSG의 getStaticProps는 빌드 타임에 실행된다.

빌드 타임에는 브라우저 요청이 아예 없으니query를 알 수가 없어서, GetStaticPathsContext 타입에 query가 아예 정의되어 있지 않음

이를 해결하기 위해서는, 빌드 타임에서 query 값을 알아야 하는데 이건 불가능하다.

😎: 정적인 페이지를 생성할 때 query string을 활용할 수 없으면 어떻게 동작시켜요? ✍️: 사전 렌더링이 끝난 뒤, 클라이언트 측에서 직접 query를 읽고 처리해야 한다. (아래의 방식처럼 해결하면 된다!)

//...
export default function Page() {
  const [books, setBooks] = useState<BookData[]>([]);

  const router = useRouter();
  const q = router.query.q as string;

  const fetchSearchResult = async () => {
    const data = await fetchBooks(q);
    setBooks(data);
  };

  useEffect(() => {
    if (q) {
      fetchSearchResult();
    }
  }, [q]);

//...

1. SSG로 기본 HTML만 내려주고,
2. 브라우저가 켜진 뒤 useRouter 훅을 이용해 router.query에서 값을 꺼내와서
3. 렌더링하는 식으로 처리

데이터 관련 부분을 제외하고 나머지 부분만 렌더링해서 브라우저에게 보내주는 걸 확인할 수 있으며,

사진 속 결과처럼 useEffect를 통해서 서버에게 데이터를 직접 요청하는 방식인 SSR으로 동작하는 걸 확인할 수 있다.

getStaticPaths

동적 라우팅 페이지(/posts/[id] 같은)에서 어떤 경로를 미리 빌드할지 정해줄 수 있다.

//...
import type { GetStaticPathsContext, InferGetStaticPropsType } from 'next';
import { ReactNode } from 'react';

export const getStaticProps = async (context: GetStaticPathsContext) => {
  const q = context.query.q as string;
  const books = await fetchBooks(q);
  return {
    props: {
      books,
    },
  };
};

export default function Page({ books }: InferGetStaticPropsType<typeof getStaticProps>) {

이때 같은 방식으로 적용하고 실행하면 아래와 같은 오류가 발생한다.

Error: getStaticPaths is required for dynamic SSG pages 
and is missing for '/book/[id]'.

이는 SSG 방식이 "어떤 경로들을 빌드 타임에 생성할지"를 미리 알아야 하는데, getSTataicPaths가 없으니 Next.js가 어떤 페이지를 만들어야 하는지 몰라서 발생한 오류이다.

✅ 해결 방법: getStaticPaths 작성

export const getStaticPaths = () => {
  return {
    paths: [
      { params: { id: '1' } },
      { params: { id: '2' } },
      { params: { id: '3' } },
    ],
    fallback: false,
  };
};

• paths: 빌드 타임에 미리 렌더링할 경로들을 배열로 작성(여기서는 /book/1 ~ /book/3)
• params: URL 파라미터를 객체 형태로 지정 (⚠️파라미터 값은 꼭 문자열로!)
• fallback: 설정하지 않은 경로로 접근했을 때 어떻게 처리할지 결정

👉 이렇게 작성하면 /book/1 ~ /book/6은 빌드 타임에 정적 페이지로 만들어지고, 그 외 경로는 404가 뜨게 된다.

fallback 옵션

위에서 사용한 fallback 옵션을 false 이외에도 유연하게 설정할 수 있다.

fallback: false

• 설정하지 않은 경로 = 404 Not Found
• 아예 빌드 타임에 지정한 path만 접근 가능

fallback: "blocking"

• 지정하는 않은 경로에 접근하면, 서버에서 해당 페이지를 즉시 생성
• 생성이 완료된 후에야 브라우저에 전달됨
• SSR처럼 동작하지만, 생성된 결과는 캐싱되어 이후에는 정적으로 제공한다.

⚠️ 주의할 점은 사전 렌더링 하는 시간이 길어지는 경우 브라우저에서 오랜 시간 기다려야 하는 상황이 발생할 수 있다. 이럴 때는 true 로 설정하면 된다.

fallback: true

• 지정하지 않은 경로 접근하는 경우, 우선 “빈 페이지”를 보여주고
• 백그라운드에서 데이터를 불러와 페이지를 완성한 뒤 교체 (Hydration 느낌!)
• 즉시 응답이 가능하지만, 초기엔 “로딩 중” 같은 처리가 필요

🔥 예외처리을 더 개선해자!

//...
export const getStaticProps = async (context: GetStaticPropsContext) => {
  const id = context.params!.id;
  const book = await fetchOneBook(Number(id));
>
  if (!book) {
    return {
      notFound: true,
    };
  }
>
  return {
    props: {
      book,
    },
  };
};
>
export default function Page({ book }: InferGetStaticPropsType<typeof getStaticProps>) {
  const router = useRouter();
>
  if (router.isFallback) return '로딩 중입니다.';
>
  const { title, subTitle, description, author, publisher, coverImgUrl } = book;
>
  return (
 //...

• useRouter의 속성 isFallback으로 fallback 상태를 확인하여, 로딩 중과 404를 구분해 사용자에게 보여줄 수 있다.

• 404인 경우에 Not Found로 이동할 수 있게 noFound 속성을 true로 설정해준다. (존재하지 않은 페이지에 접근하면 이래의 이미지의 결과를 확인할 수 있다.)

1. 사전 렌더링과 데이터 패칭

리액트 앱에서는 보통 아래와 같이 데이터를 패칭한다.

export default function Page() {
  const [state, setState] = useState();

  const fetchData = async () => {
    const response = await fetch("...");
    const data = await response.json();
    setState(data);
  };

  useEffect(() => {
    fetchData();
  }, []);

  if (!state) return "Loading...";

  return <div>...</div>;
}

동작 순서

1. state 생성
2. 데이터 패칭 함수 정의
3. 컴포넌트 마운트 시점에 호출
4. 로딩 중이면 예외처리

👉 문제는 컴포넌트가 마운트된 이후에 호출되기 때문에, 데이터가 화면에 뜨기까지 시간이 오래 걸린다는 점. 즉, 리액트의 느린 FCP(First Contentful Paint) 문제

Next.js로 느린 FCP 해결하기

Next.js는 사전 렌더링(Pre-Rendering)을 통해 느린 FCP 문제를 해결한다.

• 초기 요청 시 서버가 HTML을 완성해 전달
• 이때 필요한 데이터를 서버에서 미리 불러와 함께 전달 가능

덕분에 화면 로딩이 훨씬 빨라짐!

😎: 서버 요청 자체가 오래 걸리면 사전 렌더링도 그만큼 지연되지 않나유? ✍️: 넥스트는 이러한 점까지 고려하여, 빌트 타임에 미리 렌더링하거나, 서버 요청 시점에 렌더링하도록 설정할 수 있게 도와준다. (아래에서 알아보자!)

사전 렌더링의 종류

1. SSR(Server Side Rendering)

• 요청이 들어올 때마다 서버에서 렌더링
• 가장 기본적인 방식

  2. SSG(Static Site Generation)

• 빌드 타임에 미리 렌더링
• 요청 시에는 완성된 정적 페이지 제공

  3. ISR(Incremental Static Regeneration)

  추후 강의에서 진행한다고 함!
• SSG + 주기적 갱신

2. SSR 실습: getServerSideProps

Next.js는 페이지 안에 약속된 이름의 getServerSideProps라는 함수를 작성하고 export하면, 자동으로 SSR 모드로 전환된다.

getServerSideProps 함수

• 페이지 컴포넌트보다 먼저 실행되어, 필요한 데이터를 미리 불러올 수 있다.
• 이때, 반환 객체 안에서 반드시 props 객체가 포함되여야 한다.

// pages/index.tsx
import type { ReactNode } from 'react';
import SearchableLayout from '@/components/searchable-layout';

export const getServerSideProps = () => {
  const data = "hello";
  return {
    props: { data },
  };
};

export default function Home({ data }: { data: string }) {
  console.log(data)
//...

콘솔을 확인해보면 props로 전달받은 데이터가 잘 출력되는 걸 확인할 수 있다.

⚠️ 서버 전용 코드 주의

getServerSideProps는 서버에서 실행되므로 window 같은 브라우저 객체는 사용이 불가하다.

// pages/index.tsx
//...
export const getServerSideProps = () => {
  const data = 'hello';
  window.location;
  return {
    props: {
      data,
    },
  };
};
//..

추가로 페이지 컴포넌트의 경우에는 서버에서 한 번, 브라우저에서 한 번 총 2번이 실행되기 때문에, 위의 window 객체를 똑같이 페이지 컴포넌트에서 사용해보면 동일한 오류가 발생한다.

😎: 그러면 브라우저에서만 실행되는 건 어떻게 해야하나요~? ✍️: 만약 브라우저 전용 코드를 사용해야 한다면, 페이지 컴포넌트의 useEffect에 넣어서 사용해야 한다. 컴포넌트 마운트 시점 이후에 출력 즉, 사전 렌더링 과정 중 서버에서 실행되지 않는 코드이기 때문에 ReferenceError: window is not defined가 발생하지 않는다.

// pages/index.tsx
//...
export default function Home({ data }: any) {
  useEffect(() => {
    console.log(window.location);
  }, []);
//...

타입 안전하게 사용하기: InferGetServerSidePropsType

Next.js는 InferGetServerSidePropsType으로 반환 타입을 자동 추론할 수 있다.

//...
export const getServerSideProps = () => {
  const data = 'hello';
  return {
    props: {
      data,
    },
  };
};

export default function Home({ data }: InferGetServerSidePropsType<typeof getServerSideProps>) {
  useEffect(() => {
    console.log(window.location);
  }, []);
//...

타입이 잘 추론된 것을 확인할 수 있다.

SSR + API 연동

API 호출 파일을 따로 관리하기 위해 src에 lib라는 폴더를 생성해준다.

// /src/lib/fetch-books.ts
import { BookData } from '@/types';

export default async function fetchBooks(): Promise<BookData[]> {
  const url = `http://localhost:12345/book`;

  try {
    const response = await fetch(url);
    if (!response.ok) {
      throw new Error();
    }
    return await response.json();
  } catch (err) {
    console.error(err);
    return [];
  }
}

getServerSideProps에서 호출은 아래와 같다.

//...
export const getServerSideProps = async () => {
  const allBooks = await fetchBooks();
  return {
    props: {
      allBooks,
    },
  };
};

export default function Home({ allBooks }: InferGetServerSidePropsType<typeof getServerSideProps>) {
//...
            <section>
        <h3>등록된 모든 도서</h3>
        {allBooks.map((book) => (
          <BookItem key={book.id} {...book} />
        ))}
      </section>
//...

이때, 여러 API를 동시에 호출하려면 Promise.all을 활용하면 된다!(당연)

export const getServerSideProps = async () => {
  const [allBooks, randomBooks] = await Promise.all([fetchBooks(), fetchRandomBooks()]);
  return {
    props: {
      allBooks,
      randomBooks,
    },
  };
};

쿼리와 URL 파라미터 사용하기

쿼리 사용하기

getServerSideProps의 인수로 context를 받아 사용할 수 있다.

export const getServerSideProps = async (context: GetServerSidePropsContext) => {
  return {
    props: {},
  };
};

이때 context라는 매개변수에 Next.js가 제공하는 GetServerSidePropsContext를 사용한다.

context라는 매개변수는 현재 브라우저로부터 받은 요청에 대한 모든 정보가 다 포함되어 있다. 콘솔로 확인해보자!

context에는 전달한 query 값이 있기 때문에 꺼내서 사용햐면 된다.

import type { GetServerSidePropsContext } from 'next';

export const getServerSideProps = async (context: GetServerSidePropsContext) => {
  const q = context.query.q;
  return {
    props: {
      q,
    },
  };
};

URL 파라미터 사용하기

마찬가지로 context의 params를 이용하여 가져오면 된다.

export const getServerSideProps = async (context: GetServerSidePropsContext) => {
  const id = context.params!.id;
  return {
    props: {},
  };
};

✅ 정리하며

• CSR의 느린 데이터 로딩 문제를 서버에서 미리 해결할 수. 있다.
• getServerSideProps 덕분에 데이터 + UI를 한번에 전달 가능하다.
• 브라우저 전용 코드는 useEffect에 넣기!
• 타입 추론은 InferGetServerSidePropsType으로 안전하게 처리 가능하다.
• 쿼리/파라미터를 쉽게 활용 가능하다.

글로벌 레이아웃 설정하기

글로벌 레이아웃은 앱의 모든 페이지를 감싸는 루트 컴포넌트에 적용한다. Page Router 기준으로 실습 파일의 루트는 _app.tsx다.

// pages/_app.tsx
import '@/styles/globals.css';
import type { AppProps } from 'next/app';

export default function App({ Component, pageProps }: AppProps) {
  return (
    <div>
      <header>header</header>
      <main>
        <Component {...pageProps} />
      </main>
      <footer>footer</footer>
    </div>
  );
}

• 루트 컴포넌트가 페이지 컴포넌트를 포함하도록 구조를 잡아준다.

이제 레이아웃을 컴포넌트로 분리해보자.

src/components/global-layout.tsx를 만들고 아래처럼 작성한다.

// src/components/global-layout.tsx
import { ReactNode } from 'react';

export default function GlobalLayout({ children }: { children: ReactNode }) {
  return (
    <div>
      <header>header</header>
      <main>{children}</main>
      <footer>footer</footer>
    </div>
  );
}

그리고 _app.tsx에서 사용한다.

// pages/_app.tsx
import GlobalLayout from '@/components/global-layout';
import '@/styles/globals.css';
import type { AppProps } from 'next/app';

export default function App({ Component, pageProps }: AppProps) {
  return (
    <GlobalLayout>
      <Component {...pageProps} />
    </GlobalLayout>
  );
}

페이지별 레이아웃 설정하기

특정 페이지군에만 검색 UI를 붙이고 싶다면, 전역이 아닌 페이지별 레이아웃을 만든다.

// src/components/searchable-layout.tsx
import { ReactNode } from 'react';

export default function SearchableLayout({ children }: { children: ReactNode }) {
  return (
    <div>
      <div>임시 서치바</div>
      {children}
    </div>
  );
}

이걸 전역 _app.tsx에 바로 끼우면 모든 페이지에 서치 바가 생긴다.

필요한 페이지에서만 쓰려면 per-page layout 패턴을 쓰자.

// pages/index.tsx
import SearchableLayout from '@/components/searchable-layout';
import type { ReactElement } from 'react';
import styles from './index.module.css';

export default function Home() {
  return (
    <>
      <h1 className={styles.h1}>인덱스</h1>
      <h2 className={styles.h2}></h2>
    </>
  );
}

// getLayout: 페이지 컴포넌트에 메서드로 선언
Home.getLayout = (page: ReactElement) => {
  return <SearchableLayout>{page}</SearchableLayout>;
};

getLayout 메서드는 페이지 렌더링 시 호출되어, 해당 페이지를 원하는 레이아웃으로 감싼다. 그리고 _app.tsx에서 이 메서드를 인식하도록 처리하면 된다.

// pages/_app.tsx
import GlobalLayout from '@/components/global-layout';
import '@/styles/globals.css';
import type { AppProps, NextPage } from 'next';
import type { ReactElement, ReactNode } from 'react';

export type NextPageWithLayout<P = {}, IP = P> = NextPage<P, IP> & {
  getLayout?: (page: ReactElement) => ReactNode;
};

type AppPropsWithLayout = AppProps & {
  Component: NextPageWithLayout;
};

export default function App({ Component, pageProps }: AppPropsWithLayout) {
  // getLayout이 없으면 기본적으로 "그냥 페이지"를 반환
  const getLayout = Component.getLayout ?? ((page: ReactElement) => page);
  return <GlobalLayout>{getLayout(<Component {...pageProps} />)}</GlobalLayout>;
}

이렇게 하면 getLayout이 없는 페이지도 타입 오류 없이 안전하게 렌더링된다.

검색 기능이 있는 레이아웃 구현하기

검색 입력 /search?q=...로 이동하는 간단한 예시에

• 검토용 trim()
• 안전한 인코딩 encodeURIComponent

을 추가하여 구현하기

// src/components/searchable-layout.tsx
import { useRouter } from 'next/router';
import { ChangeEvent, KeyboardEvent, ReactNode, useEffect, useState } from 'react';

export default function SearchableLayout({ children }: { children: ReactNode }) {
  const router = useRouter();
  const [search, setSearch] = useState('');

  // 현재 URL의 쿼리(q)와 상태를 동기화
  const q = (router.query.q as string) ?? '';

  useEffect(() => {
    setSearch(q);
  }, [q]);

  const onChangeSearch = (e: ChangeEvent<HTMLInputElement>) => {
    setSearch(e.target.value);
  };

  const submit = () => {
    const next = search.trim();
    if (!next || next === q) return;
    router.push(`/search?q=${encodeURIComponent(next)}`);
  };

  const onKeyDown = (e: KeyboardEvent<HTMLInputElement>) => {
    if (e.key === 'Enter') submit();
  };

  return (
    <div>
      <form
        onSubmit={(e) => {
          e.preventDefault();
          submit();
        }}
      >
        <input
          value={search}
          onChange={onChangeSearch}
          onKeyDown={onKeyDown}
          placeholder="검색어를 입력해주세요..."
          aria-label="검색어"
        />
        <button type="submit">검색</button>
      </form>
      {children}
    </div>
  );
}

✅ 정리

• Next.js는 페이지 컴포넌트를 _app.tsx의 Component로 전달하고, 우리가 임의로 부착한 getLayout 메서드도 함께 전달할 수 있다.
• _app.tsx에서 GlobalLayout으로 한 번 감싸고, 페이지에 getLayout이 있으면 추가로 원하는 레이아웃으로 감싸 최종 UI를 만들 수 있다.

// pages/_app.tsx
const getLayout = Component.getLayout ?? ((page) => page);
return <GlobalLayout>{getLayout(<Component {...pageProps} />)}</GlobalLayout>;

스타일링

Next.js에서 스타일링하는 방법을 알아보자!

먼저 간단히 src > pages > index.tsx 안에서 인라인 스타일을 적용해볼 수 있다.

export default function Home() {
  return <h1 style={{ color: 'red' }}>인덱스</h1>;
}

하지만 인라인 방식은 코드가 지저분해지고, 재사용성이 떨어진다는 단점이 있다. 그래서 보통은 CSS 파일을 따로 만들어 관리한다.

❌ 잘못된 방식: 전역 CSS를 직접 import

import './index.css';

export default function Home() {
  return <h1 className="title">인덱스</h1>;
}

이렇게 작성하면 Build Error가 발생한다.

Next.js에서는 전역 CSS를 pages/_app.tsx에서만 가져올 수 있고, 일반 페이지 컴포넌트에서는 전역 CSS 파일을 바로 import하는 것을 금지하고 있기 때문!

⚠️ 이유

• 중복된 스타일링으로 인한 충돌 방지
• CSS 관리의 일관성 확보

✅ 권장 방식: CSS Module 사용하기

페이지 단위에서 개별 스타일을 적용하고 싶다면 CSS Module을 활용해야 한다.

• 파일명은 반드시 *.module.css 형태

import style from './index.module.css';

export default function Home() {
  return <h1 className={style.h1}>인덱스</h1>;
}

index.module.css

.h1 {
  color: red;
}

API Routes

Next.js에서는 별도의 백엔드 서버 없이도 간단한 API 엔드포인트를 만들 수 있다. pages/api 폴더 하위에 파일을 만들면, 파일 이름이 곧 API 경로가 된다.

예) pages/api/hello.ts → /api/hello

API Routes는 서버 사이드에서 실행된다. 덕분에 브라우저에 노출되지 않으며, DB 접근/비밀키 사용/외부 API 호출 등의 서버 로직을 넣기에 적합하다!

가장 기본 예제: /api/hello

// pages/api/hello.ts
// Next.js API route support: https://nextjs.org/docs/api-routes/introduction
import type { NextApiRequest, NextApiResponse } from "next";

type Data = { name: string };

export default function handler(
  req: NextApiRequest,
  res: NextApiResponse<Data>
) {
  res.status(200).json({ name: "John Doe" });
}

• handler 함수가 요청을 받아 응답을 보낸다.
• res.status(200).json(...) 처럼 상태 코드와 JSON 응답을 보낼 수 있다.

⏱️ 간단한 API 추가: /api/time

// pages/api/time.ts
import type { NextApiRequest, NextApiResponse } from "next";

export default function handler(req: NextApiRequest, res: NextApiResponse) {
  const date = new Date();
  res.status(200).json({ time: date.toLocaleDateString() });
}

브라우저에서 http://localhost:3000/api/time으로 접속하면 날짜가 JSON으로 반환된다.

🧭 요청 메서드 분기 (GET/POST 등)

하나의 파일 안에서 HTTP 메서드별로 분기해 다양한 동작을 구현할 수 있다.

// pages/api/users.ts
import type { NextApiRequest, NextApiResponse } from "next";

export default function handler(req: NextApiRequest, res: NextApiResponse) {
  if (req.method === "GET") {
    return res.status(200).json({ users: ["alice", "bob"] });
  }
  if (req.method === "POST") {
    // req.body 사용 가능 (예: JSON 파싱)
    return res.status(201).json({ ok: true });
  }
  res.setHeader("Allow", ["GET", "POST"]);
  return res.status(405).end("Method Not Allowed");
}