Next.js에서 next.config.ts 이해하기

사이드 프로젝트를 진행하면서 세팅을 위해 Next.js를 설치했다.
설치한 이후에 Next.js 환경설정 단계에서 next.config.ts라는 파일이 루트에 자동으로 생기는데
이 next.config.ts 파일에 대해 자세히 살펴보려고한다.

Next.js 프로젝트를 열어보면 루트에 next.config.ts라는 파일이 있다.
겉보기엔 단순한 설정 파일 같지만, 사실은 앱 전체 동작을 제어하는 제어판이다.

왜 필요한가?

Next.js는 기본값만으로도 작동하지만, 실제 서비스에서는 이런 상황이 생긴다.

• 외부 이미지(CDN, 스토리지) 불러오기 (악성 이미지일 수 있음!)
• 보안 헤더 추가
• 개발 환경과 운영 환경 분리
• 다국어 지원
• 번들 크기 최적화

이걸 코드 곳곳에 넣으면 번거롭다. next.config.ts는 이 모든 걸 한 곳에서 관리하게 해준다.

어떤 문제를 해결하나?

• 외부 이미지 차단 문제
  Next.js의 <Image />는 성능 최적화를 위해 등록된 도메인에서만 이미지를 가져올 수 있다.
  예를 들어 Unsplash나 Supabase Storage 이미지를 쓰려면 도메인을 next.config.ts에 등록해야 한다.
  
  
• 보안 부족 문제
  기본 응답에는 보안 헤더가 거의 없다.
  CSP, X-Frame-Options, Strict-Transport-Security 같은 헤더를 next.config.ts에서 추가하면 모든 페이지에 자동 반영된다.
  
  
• 환경별 설정 문제
  개발용(local)과 운영용(production)에서 요구사항이 다르다.
  예를 들어 개발에선 unsafe-eval을 허용해야 하지만, 운영에선 차단해야 한다.
  process.env.NODE_ENV 값으로 분기해 조건을 달리 줄 수 있다.
  
  
• 실험 기능 사용 문제
  Next.js는 새로운 기능을 experimental 플래그로 제공한다.
  typedRoutes, optimizePackageImports 같은 기능을 켜고 끄는 것도 여기서 한다.
  
  
• 다국어(i18n) 지원 문제
  다국어를 지원하려면 라우팅에 i18n 설정이 필요하다.
  이를 next.config.ts에 추가해 관리할 수 있다.
  
  
• Webpack 번들링 문제
  ../../../components/Button 같은 긴 경로 대신 @/components/Button처럼 간단히 쓰려면 alias 설정을 해줘야 한다.
  이것도 next.config.ts에서 처리한다.

어떻게 쓰는 건가?

구조는 간단하다. module.exports 안에 옵션을 넣으면 된다.

// next.config.ts
module.exports = {
  images: {
    domains: ['images.unsplash.com'], // 외부 이미지 허용
  },
  async headers() {
    return [
      {
        source: '/:path*',
        headers: [{ key: 'X-Frame-Options', value: 'DENY' }], // 보안 헤더
      },
    ]
  },
  experimental: {
    typedRoutes: true, // 실험 기능
  },
}

결과적으로 뭐가 좋아지나?

• 외부 이미지를 성능 최적화된 형태로 안전하게 불러올 수 있다.
• 모든 페이지에 기본 보안 헤더가 적용된다.
• 환경별로 다른 설정을 줄 수 있어 운영이 편리하다.
• 필요할 때만 실험 기능을 켜고 성능 최적화를 적용할 수 있다.

커스텀 옵션은 정말 많다

여기까지 본 건 자주 쓰이는 일부 옵션일 뿐이다.
실제로 next.config.ts는 엄청나게 많은 설정 포인트를 제공한다.
세팅에서의 커스텀 설정을 할 수도 있고 나중에 프로젝트 개발을 할 때 또 다르게 커스텀 설정을 할 수도 있는 것이다.

• 빌드 경로(distDir)
• URL 끝 슬래시 여부(trailingSlash)
• 서버 사이드 렌더링 최적화(output)
• 리디렉션, 리라이트, 헤더 규칙
• 이미지 remotePatterns 세부 설정

즉, 프로젝트 성격에 맞게 커스텀할 수 있는 범위가 넓다.
따라서 공식 문서나 구글링을 통해 다양한 옵션을 찾아보는 게 좋다.
필요할 때마다 한두 개씩 적용해보면 금방 익숙해진다.




나는 next.config.ts를 “Next.js 앱의 제어판”이라고 본다.
작은 프로젝트에서는 몰라도 되지만, 서비스가 커질수록 반드시 손봐야 하는 부분이다.