[next.js] 빌드 최적화 - 프로덕션 번들에서 개발 전용 코드 제외하기

프로젝트 규모가 커질수록 Next.js 프로덕션 빌드 시간이 점점 늘어나는 문제를 체감하게 됐다.
“코드가 늘면 빌드가 느려지는 건 당연한 거 아닌가?” 싶지만,

자세히 보면 프로덕션에서 사용하지 않는 코드까지 빌드 파이프라인이 처리하면서 시간을 잡아먹는 구간들이 있다.

 

이번 글은 그중 하나였던 React Query / Jotai DevTools를 _app에 정적 import로 넣어둔 구조를 개선해서,

빌드 시간을 줄인 과정을 정리한 것이다.

 

1. 문제: DevTools를 그냥 넣으면?

개발 편의를 위해 @tanstack/react-query-devtools, jotai-devtools를 쓰는 경우,

보통은 상단에서 정적 import 한 뒤 _app 안에서 컴포넌트로 렌더링하게 된다.

import { ReactQueryDevtools } from '@tanstack/react-query-devtools';
import { DevTools } from 'jotai-devtools';

function App() {
  return (
    <>
      {/* ... */}
      <ReactQueryDevtools initialIsOpen={false} />
      <DevTools position="bottom-left" />
    </>
  );
}

 

이렇게 하면 몇 가지 부작용이 생긴다.

먼저 프로덕션에서도 DevTools 코드가 번들에 포함될 수 있다. 정적 import는 “이 파일을 무조건 불러온다”는 의미이기 때문에, Webpack·Next.js가 프로덕션 빌드를 할 때도 해당 모듈을 번들에 넣을 수 있다. 사용자는 DevTools를 쓰지 않는데, 불필요한 코드가 내려가서 번들 크기와 파싱 비용이 늘어난다.

 

둘째로 초기 로딩 시점에 DevTools 청크까지 같이 로드될 수 있다. 메인 번들과 함께 혹은 그 직후에 DevTools 관련 청크가 요청되기 때문에, “첫 화면을 그리기까지 걸리는 시간”(TTI)이 늘어날 수 있다. 개발할 때도 첫 로딩이 무거워지면 체감 속도가 떨어진다.

 

셋째로 빌드할 때마다 DevTools 의존성을 파싱·처리하게 된다. 프로덕션 빌드에서도 해당 패키지를 해석하고, tree-shaking·최적화 대상으로 넣어야 하므로 빌드 시간과 메모리 사용량이 조금이라도 늘어난다.

 

결국 DevTools가 “개발용”임에도 빌드 과정에서 꾸준히 처리 대상이 된다

정리하면, “개발용” 코드인 DevTools가 프로덕션 번들, 빌드 과정, 개발 시 로딩 경험 모두에 영향을 주는 구조가 된다.

 

2. 해결: 환경 분기 + Dynamic Import

따라서, 프로젝트에서는 “환경에 따라 DevTools를 아예 부르지 않거나, 부를 때만 동적으로 불러오기”로 바꿨다.

다시 정리하면 이런 전략이다.

• 프로덕션에서는 아예 DevTools를 렌더하지 않는다
• 개발 환경에서는 필요할 때만 동적으로 로드한다
• DevTools는 브라우저 API(window/document)에 의존하므로 SSR은 끈다

 

코드는 아래와 같다.

import dynamic from 'next/dynamic';

const isProd = process.env.NODE_ENV === 'production';

const ReactQueryDevtools = isProd
  ? () => null
  : dynamic(
      () =>
        import('@tanstack/react-query-devtools').then(
          (mod) => mod.ReactQueryDevtools,
        ),
      { ssr: false },
    );

const JotaiDevTools = isProd
  ? () => null
  : dynamic(() => import('jotai-devtools').then((mod) => mod.DevTools), {
      ssr: false,
    });

 

프로덕션(NODE_ENV === 'production')일 때는 ReactQueryDevtools와 JotaiDevTools를  “아무것도 그리지 않는 컴포넌트” () => null로 둔다.

 

이렇게 하면 프로덕션 빌드 시 isProd가 true로 고정되기 때문에, dynamic(() => import(...))를 호출하는 분기는 실행되지 않는 dead code가 된다. 번들러는 이 경로를 제거할 수 있고, DevTools 패키지를 불러오는 코드는 실행 경로에 남지 않는다.

 

개발 환경에서는 next/dynamic으로 해당 패키지를 동적 import한다. “앱이 로드될 때 한 번에”가 아니라,

해당 컴포넌트가 실제로 마운트될 때 그때 가서 해당 모듈을 요청한다. 그리고 ssr: false를 주어 서버에서는 이 컴포넌트를 렌더하지 않고, 브라우저에서만 마운트되도록 했다.

 

DevTools는 DOM·window 같은 브라우저 전용 API를 쓰기 때문에, SSR 단계에서 렌더링하면 에러가 나거나 불필요한 코드가 서버에 올라갈 수 있어서 클라이언트 전용으로 두는 것이 맞다.

사용하는 쪽 코드는 기존과 동일하다. _app 안에서 그대로 <JotaiDevTools />, <ReactQueryDevtools />만 쓰면 되고, 환경에 따라 위에서 정의한 “빈 컴포넌트” 또는 “동적으로 불러온 DevTools”가 렌더링된다.

<JotaiDevTools position="bottom-left" />
<ReactQueryDevtools initialIsOpen={false} />

 

3. 왜 이렇게 하면 좋은가?

3.1 프로덕션 번들·빌드

Next.js·Webpack은 빌드 시점에 process.env.NODE_ENV를 실제 값(예: 'production')으로 치환한다.

그래서 프로덕션 빌드에서는 isProd가 항상 true가 되고, 삼항 연산자에서 dynamic(() => import(...)) 쪽은 “절대 실행되지 않는 코드”가 된다.

 

번들러는 이런 dead code를 제거할 여지가 생기게 된다.

최소한 “프로덕션 실행 결과물” 관점에서는 DevTools 패키지를 가리키는 import(...) 경로는 프로덕션 번들에 포함되지 않는다.

 

그 결과, DevTools 패키지는 프로덕션 번들에 들어가지 않아 번들 크기가 줄고, 빌드할 때도 해당 모듈을 파싱·최적화하지 않아 빌드 시간이 조금이라도 단축된다. “개발용” 코드가 프로덕션 결과물과 빌드 과정 양쪽에서 분리되는 효과가 있다.

 

3.2 개발 환경 로딩

dynamic(() => import(...))를 쓰면 Webpack이 그 부분을 별도 청크(chunk)로 분리한다.

즉, 메인 번들(_app이 포함된 청크)과 DevTools가 들어 있는 청크가 따로 만들어진다.

 

실제 로딩 순서는 이렇게 된다. 브라우저가 먼저 메인 번들을 받아서 앱을 그린다. 그다음 <ReactQueryDevtools />, <JotaiDevTools />가 마운트될 때 각각의 동적 import가 실행되면서 DevTools 청크를 요청한다.

 

따라서 초기 로딩에서는 DevTools 코드를 기다리지 않아도 되고, “첫 화면이 나오는 시간”이 짧아진다. 개발할 때 첫 화면이 빨리 뜨고, DevTools는 필요할 때만 별도로 로드되는 구조가 된다.

 

3.3 SSR

DevTools는 window, document, React DevTools 확장과 같은 DOM·브라우저 전용 API에 의존한다.

서버에는 이런 API가 없기 때문에, SSR 단계에서 DevTools 컴포넌트를 렌더하려고 하면 에러가 나거나 불필요한 polyfill·분기가 들어갈 수 있다.

 

next/dynamic에 ssr: false를 주면, 해당 컴포넌트는 서버에서는 아예 렌더되지 않고, 클라이언트에서만 마운트된다.

그래서 서버 번들에도 DevTools가 들어가지 않고, 브라우저에서만 “동적 import → 마운트”가 일어나도록 할 수 있다.

DevTools처럼 브라우저 전용인 UI는 ssr: false로 두는 것이 맞다.

---

4. 결과 : 빌드 시간이 크게 줄었다.

 

• Before: Done in 183.94s
• After: Done in 52.03s

반면, First Load JS shared by all은 4.23 MB로 동일했다.
즉 이번 변경은 “번들 크기 감소”보다는 빌드 파이프라인 부담 감소(=빌드 시간 단축) 쪽 효과가 더 크게 나타난 케이스에 가깝다.

 

결론적으로: “프로덕션에서 필요 없는 코드가 _app 경로에 얹혀 있던 구조”를 분리했더니 빌드 시간 개선이 크게 발생했다.

 

 

 

5. 정리

구분	일반 import	환경 분기 + Dynamic Import
프로덕션 번들	DevTools 포함 가능	제외됨 (dead code 제거)
개발 초기 로딩	메인 번들과 함께 로드	별도 청크로 지연 로드
빌드	매번 DevTools 처리	프로덕션에서는 미포함

 

Next.js에서 DevTools를 쓸 때 “환경 분기 + dynamic import + ssr: false” 조합을 쓰면, 프로덕션 번들에는 DevTools가 들어가지 않고, 프로덕션 빌드 시간은 줄며, 개발 시에는 초기 로딩이 가벼워진다.

“개발용 코드는 개발 환경에서만, 필요할 때만” 로드 되도록 분리하는 패턴이 된다.

 

 

다음에 같이 보면 좋은 것들

- Bundle Analyzer로 DevTools 청크 포함 여부 확인

 

2026.02.03 - [Development/Next.js] - [Next.js] 성능 최적화 - 번들 사이즈 개선 (feat. bundle-analyzer)

이 글감보다 먼저 작성되었지만, 해당 글감이 더 먼저 작업했던 일이었다.

아직 번들 사이즈 개선과 빌드 시간 단축 브랜치를 머지하는 작업을 하지 않았어서..

머지 후 해당 글에 결과를 추가해보겠다..