Next.js App Router Guide: Local Development (Dev 환경 최적화)

로컬(dev)과 프로덕션(build)의 차이

next dev: 필요한 라우트만 열거나 이동할 때 컴파일 (빠른 시작 / 메모리 절약)
next build + next start: 프로덕션 최적화(minify, content hash 등) 적용

로컬 성능이 느릴 때 체크 순서

1) Antivirus(보안 프로그램) 영향 확인

파일 접근이 느려져 컴파일/리빌드가 크게 느려질 수 있습니다.

Windows: 프로젝트 폴더를 Defender 예외 목록에 추가
macOS: 터미널에서 Gatekeeper developer-mode 활성화 안내가 있음

2) Next.js 최신 + Turbopack 사용

Turbopack은 dev 기본 번들러이며 webpack보다 빠를 수 있습니다.

npm install next@latest
npm run dev    # 기본: Turbopack
npm run dev --webpack  # 필요 시 webpack으로 opt-in

3) Import 패턴 점검

아이콘 라이브러리

react-icons 같은 패키지는 수천 개 모듈을 끌어와 빌드가 느려질 수 있어요. 필요한 아이콘만 “직접 경로 import” 하는 패턴을 고려합니다.

// 대신:
import { TriangleIcon } from '@phosphor-icons/react'

// 이렇게:
import { TriangleIcon } from '@phosphor-icons/react/dist/csr/Triangle'

Barrel file 피하기

index.ts에서 여러 파일을 한 번에 export하는 “barrel files”는 빌드 속도를 느리게 할 수 있습니다.
가능하면 정확한 파일 경로로 직접 import를 고려합니다.

optimizePackageImports (실험 옵션)

barrel 구조의 패키지를 쓰는 경우 Next.js가 import를 최적화하도록 설정할 수 있습니다.

// next.config.js
module.exports = {
  experimental: {
    optimizePackageImports: ['package-name'],
  },
}

Turbopack은 import 분석/최적화를 자동으로 수행하므로 이 설정이 필요 없을 수 있습니다.

4) Tailwind CSS content 스캔 범위 확인

content에 node_modules 같은 큰 디렉토리가 포함되면 매우 느려질 수 있습니다.

// tailwind.config.js (예시)
module.exports = {
  content: [
    './src/**/*.{js,ts,jsx,tsx}', // Good
    // 너무 넓을 수 있음: packages/**/node_modules 까지 매칭될 수 있음
    // '../../packages/**/*.{js,ts,jsx,tsx}',
  ],
}

5) 커스텀 webpack 설정 점검

추가한 webpack 설정이 dev 컴파일을 느리게 할 수 있습니다.

로컬 dev에서는 필요 없는 설정을 빼거나
프로덕션 빌드에만 적용하거나
Turbopack 기본을 쓰고 “loader” 설정으로 대체하는 접근을 고려

6) 메모리 사용 최적화

앱이 큰 경우 더 많은 메모리가 필요할 수 있습니다(가이드에서 별도 문서 링크 제공).

7) Server Components + 데이터 페칭 비용

Server Component 변경은 로컬에서 페이지 전체 리렌더/리페치가 발생할 수 있습니다.
가이드는 serverComponentsHmrCache(실험 옵션)로 HMR 동안 fetch 응답을 캐시해 로컬 응답 속도 + 외부 API 비용을 줄일 수 있다고 안내합니다.

8) Docker 대신 로컬 실행 고려 (Mac/Windows)

Mac/Windows에서 Docker는 파일시스템 접근이 느려서 HMR이 크게 느려질 수 있습니다.

개발은 로컬(npm run dev, pnpm dev) 권장
Docker는 프로덕션/테스트용으로 주로 사용
꼭 Docker dev가 필요하면 Linux 머신/VM 고려

문제 원인 찾기 도구

fetch 로깅 강화

// next.config.js
module.exports = {
  logging: {
    fetches: {
      fullUrl: true,
    },
  },
}

Turbopack tracing

NEXT_TURBOPACK_TRACING=1 npm run dev
# 문제 재현 후 종료
npx next internal trace .next/dev/trace-turbopack
# (구버전은 turbo-trace-server 명령)

트레이스 파일: .next/dev/trace-turbopack
뷰어: https://trace.nextjs.org/
기본 dev 디렉토리 .next/dev는 isolatedDevBuild로 제어 가능

# Next.js App Router Guide: Local Development (Dev 환경 최적화)