Next.js App Router 공식 튜토리얼 (Chapter 1~3) 핵심 개념 정리

About this offer

1. app , app/lib , app/ui , public 폴더의 역할과 Starter 프로젝트 구조 /app : Next.js App Router의 모든 라우트(routes), 컴포넌트, 로직 이 위치하는 최상위 디렉터리입니다. 폴더 기반 라우팅을 지원하며, page.tsx (고유 UI 화면), layout.tsx (여러 페이지 간 공유되는 UI 프레임) 등의 특수 파일들이 포함됩니다. /app/lib : 애플리케이션 전반에서 사용되는 유틸리티 함수, 비즈니스 로직, 데이터 타입 정의, 데이터베이스 쿼리 함수 ( definitions.ts , data.ts , utils.ts 등)를 보관하는 폴더입니다. /app/ui : 카드, 버튼, 내비게이션 바, 폼 등과 같이 애플리케이션의 재사용 가능한 모든 UI 컴포넌트 ( buttons.tsx , invoices/table.tsx 등)를 모아두는 곳입니다. /public : 이미지( hero-desktop.png , logo.png ), 아이콘( favicon.ico ), 폰트 파일 등 정적 에셋(Static Assets)을 호스팅하는 폴더입니다. 빌드 후 루트 URL( / ) 기준으로 직접 접근 가능합니다 (예: /public/logo.png $\rightarrow$ src="/logo.png" ). 2. 개발 서버 실행 과정과 pnpm dev , 프로덕션 빌드의 의미 pnpm dev (Development Mode) : 개발용 로컬 서버(기본 포트: 3000)를 구동합니다. 빠른 개발 피드백을 위해 Fast Refresh (HMR)를 활성화하며, 소스 코드가 수정될 때마다 해당 모듈만 즉시 다시 컴파일합니다. TypeScript 타입 체크, 친절한 디버깅용 에러 오버레이가 제공됩니다. 프로덕션 빌드 ( pnpm build & pnpm start ) : pnpm build : 배포 가능한 최적화된 프로덕션 번들을 생성합니다. React Server Components(RSC) 컴파일, 정적 라우트 프리렌더링(SSG), 자바스크립트/CSS 압축 및 트리쉐이킹(Tree-shaking)이 수행됩니다. pnpm start : 생성된 프로덕션 빌드 아티팩트( .next 폴더)를 활용해 실제 서비스 환경과 동일한 고성능 서버를 구동합니다. 3. Global CSS, Tailwind CSS, CSS Modules의 차이 Next.js는 다양한 스타일링 방식을 기본 지원하며 각 도구의 성격과 적용 방식이 다릅니다: 구분 적용 방식 및 특징 장점 및 주의점 Global CSS 최상위 레이아웃( app/layout.tsx )에서 import '@/app/ui/global.css' 형태로 임포트하여 전체 앱에 일괄 적용 리셋 CSS나 타이포그래피 기본값 등 전역 스타일에 적합하지만, 전역 클래스명 충돌(Class Collision) 가능성이 있음 Tailwind CSS 유틸리티 퍼스트(Utility-First) CSS 프레임워크. HTML/JSX 태그의 className 에 유틸리티 클래스( flex , text-blue-500 등)를 직접 작성 별도의 CSS 파일을 왕복하지 않고 인라인 형태로 빠르게 작성 가능하며, 빌드 시 사용된 클래스만 추출해 번들 크기가 매우 작음 CSS Modules [name].module.css 명명 규칙을 사용하며, 파일 단위로 CSS를 컴포넌트에 한정( Scoped ) 빌드 시 각 클래스명에 고유한 해시(예: title_abc123 )가 자동 부여되어 클래스명 충돌을 완벽히 방지 4. clsx 를 이용한 상태별 조건부 클래스 적용 배경 : 요소의 상태(예: pending , paid , 활성/비활성 등)에 따라 적용해야 할 클래스명이 동적으로 달라지는 경우, 템플릿 리터럴( )로만 작성하면 코드가 복잡해지고 공백 처리가 번거로워집니다. 동작 원리 : clsx 는 객체 또는 인자 기반으로 조건식이 참( truthy )일 때만 클래스 문자열을 결합해 반환하는 유틸리티 라이브러리입니다. 공식 튜토리얼 예시 : import clsx from 'clsx'; export default function InvoiceStatus({ status }: { status: string }) { return ( <span className={clsx( 'inline-flex items-center rounded-full px-2 py-1 text-sm', { 'bg-gray-100 text-gray-500': status === 'pending', 'bg-green-500 text-white': status === 'paid', }, )} > {status} ); } ``` 5. 웹 폰트가 레이아웃 이동을 발생시키는 이유와 CLS (Cumulative Layout Shift) CLS (누적 레이아웃 이동) 발생 원인 : 외부 웹 폰트(Google Fonts 등)를 브라우저에서 네트워크로 다운로드할 때, 브라우저는 폰트가 로드되기 전까지 시스템 대체 폰트(Fallback Font)를 먼저 렌더링(FOUT - Flash of Unstyled Text)하거나 텍스트를 숨깁니다(FOIT - Flash of Invisible Text). 폰트 다운로드가 완료되어 웹 폰트가 적용되는 순간, 대체 폰트와 실제 웹 폰트 간의 글자 폭, 높이, 자간 차이 로 인해 주변 텍스트와 UI 요소들의 위치가 갑자기 밀려나는 레이아웃 이동이 발생합니다. 영향 : 사용자가 버튼을 잘못 클릭하게 만드는 등 UX를 해치며, Google Core Web Vitals의 핵심 성능 지표인 CLS 점수를 악화 시킵니다. 6. next/font 의 빌드 시점 폰트 최적화 Next.js는 next/font 모듈(예: next/font/google , next/font/local )을 통해 폰트를 완전히 최적화합니다: 빌드 시점 다운로드 & 호스팅 (Zero Extra Network Request) : 빌드 시점에 외부 폰트 파일(예: Google Fonts)을 다운로드하여 다른 정적 에셋과 함께 애플리케이션 번들 내에 저장합니다. 브라우저가 Google 서버 등 외부 네트워크로 추가 폰트 요청을 보내지 않으므로 프라이버시가 보호되고 다운로드 지연이 없습니다. 레이아웃 이동 제거 (Zero Layout Shift) : CSS size-adjust 속성 등을 활용하여 대체 폰트의 크기와 비율을 웹 폰트와 정확히 일치하도록 자동 보정해 CLS를 0으로 만듭니다 . 서브셋(Subsets) 최적화 : 필요한 문자 집합( subsets: ['latin'] 등)만 추출하여 폰트 파일의 용량을 크게 줄입니다. 7. 일반 이미지 요소( <img> )와 next/image 의 차이, 크기 지정과 반응형 이미지 Next.js의 <Image> 컴포넌트는 HTML <img> 태그의 확장판으로 자동 이미지 최적화(Automatic Image Optimization)를 제공합니다. 비교 항목 일반 <img> 태그 Next.js <Image/> 레이아웃 이동(CLS) 이미지 로드 전 영역 크기가 확보되지 않으면 아래 콘텐츠가 밀려남 width , height 를 강제 지정하거나 fill 을 사용하여 자리 표시 영역을 확보, CLS 원천 방지 포맷 최적화 원본 포맷(PNG, JPEG 등) 그대로 다운로드 브라우저 지원 여부에 따라 최신 포맷인 WebP, AVIF로 자동 변환 반응형 리사이징 화면 크기와 상관없이 동일한 크기의 원본 파일 전달 가능성 높음 디바이스 해상도 및 뷰포트 크기에 맞춰 적절한 크기로 서버에서 실시간 리사이징 로딩 전략 기본값 즉시 로딩 (별도 수동 loading="lazy" 속성 필요) 기본적으로 뷰포트에 들어올 때 Lazy Loading 처리 ( priority 속성 지정 시 LCP 대상 이미지를 우선 사전 로드) 크기 지정 원칙 : 원격/로컬 이미지 상관없이 화면에 렌더링될 때의 비율을 Next.js가 미리 파악할 수 있도록 width 와 height 를 명시 해야 합니다. 동적 크기나 부모 컨테이너 크기에 맞춰야 할 때는 fill 속성을 사용하고, 부모 요소에 position: relative 와 sizes 속성을 지정합니다. 데스크톱/모바일별 반응형 이미지를 보여줄 때는 Tailwind의 반응형 클래스(예: hidden md:block , block md:hidden )를 조합하여 디바이스별로 최적화된 이미지를 분기 렌더링합니다.