Next.js Agent Skill과 Turbopack 모듈 그래프로 클라이언트 JS 번들 줄이는 방법

next-bundle-optimizer로 정적 import 누수를 찾고 수정 전후 스냅샷으로 검증하는 절차

Next.js 번들 줄이기 썸네일

핵심 요약

  1. Next.js 16.4에 도입된 next-bundle-optimizer Agent Skill은 Turbopack의 모듈 그래프를 에이전트에게 제공해, 사람이 찾기 힘든 정적 import 누수와 중복 의존성을 자동으로 찾아낸다.
  2. 가장 흔하고 효과가 큰 수정 패턴은 next/dynamic이나 React.lazy()로 감싼 무거운 컴포넌트에서 상수·유틸리티를 함께 정적 import해 지연 로딩이 깨진 사슬을 분리하는 것이다.
  3. 에이전트에게 수정을 맡길 때는 반드시 수정 전 스냅샷 저장 → 코드 수정 → 수정 후 스냅샷 비교 순서를 강제해 실제 초기 JS 전송량이 몇 KB 줄었는지 수치로 확인해야 한다.

웹 애플리케이션에 기능을 계속 추가하다 보면 어느 순간 초기 로딩에 내려받는 클라이언트 JavaScript 번들 크기가 수 메가바이트까지 불어난다. 기존의 시각적 트리맵(@next/bundle-analyzer)은 어떤 패키지가 큰지는 보여주지만, '수백 개의 파일 중 대체 어느 import 경로 때문에 이 무거운 모듈이 초기 청크에 딸려 들어왔는지' 역추적하는 일은 여전히 사람의 수작업에 의존했다. 이 글은 2026년 10월 28일 Next.js 팀이 공개한 next-bundle-optimizer Agent Skill과 Turbopack 모듈 그래프를 연결해, 코딩 에이전트가 번들 비대화 원인을 자동 진단하고 스냅샷 비교로 검증하는 절차를 다룬다.

10월 28일 공개된 Next.js Agent Skill: 에이전트에게 Turbopack 모듈 그래프를 쥐여주다

Frontend Newsletter 11월 1일호와 Next.js 공식 발표(Ship less JavaScript in Next.js with your AI agent)에 따르면, Next.js 16.4 이상 환경에서 동작하는 next-bundle-optimizer 스킬은 Turbopack이 생성하는 정밀한 모듈 그래프(Module Graph)와 청크 스냅샷(JSON)을 AI 코딩 에이전트가 직접 읽고 쿼리할 수 있게 해준다.

기존 Next.js Core Web Vitals(LCP·INP·CLS) 지표 진단 가이드가 브라우저에 나타난 결과 지표를 보고 원인을 좁혀가는 방법이었다면, 이 스킬은 빌드 산출물의 의존성 그래프 자체를 에이전트에게 넘겨 원인 발견 → 코드 리팩토링 → 재빌드 후 바이트 단위 비교까지 자동화하는 워크플로우다.

에이전트가 모듈 그래프에서 집중적으로 찾아내는 3가지 병목 패턴

사람이 눈으로 찾기 힘들지만 next-bundle-optimizer 스킬이 Turbopack 그래프를 순회하며 정확히 짚어내는 대표적인 문제는 다음 세 가지다.

  1. Lazy Loading(next/dynamic / React.lazy)을 무력화하는 숨은 정적 Import: 특정 화면에서 무거운 에디터나 차트 컴포넌트를 dynamic(() => import('./HeavyChart'))로 분리해 두었더라도, 같은 라우트에 포함된 다른 유틸리티 파일이나 배럴 파일(index.ts)이 HeavyChart.tsx 안의 작은 상수나 타입 하나를 정적 import하고 있으면 번들러는 결국 전체 모듈을 초기 청크에 포함시킨다.
  2. 중복된 의존성(Duplicate Dependencies)과 구버전 패키지 혼입: 서드파티 라이브러리가 각기 다른 메이저 버전의 date-fns, lodash, 아이콘 세트를 참조해 동일 기능의 코드가 클라이언트 번들에 두세 번 중복 포함되는 지점을 찾아낸다.
  3. Tree-shaking 실패 지점과 서버/클라이언트 경계 누수: "use client"가 파일 최상단에 너무 넓게 선언되어 서버 컴포넌트에 남아 있을 수 있는 마크다운 파서나 스키마 검증기까지 클라이언트 번들로 넘어간 경로(Next.js 서버·클라이언트 컴포넌트 경계 설계 참고)를 추적한다.

실제로 Vercel 내부 팀은 이 에이전트 스킬을 v0와 vercel.com 프로덕션 저장소에 실행해, lazy() 래퍼를 우회하던 정적 import 사슬을 끊어내는 것만으로 압축 기준 약 2MB에 달하는 클라이언트 JavaScript를 제거하거나 지연 로딩으로 전환했다고 보고했다.

실습: 내 Next.js 프로젝트에 스킬을 설치하고 번들 전후 스냅샷 비교하기

Next.js 16.4 이상 및 Turbopack이 적용된 프로젝트에서 next-bundle-optimizer 스킬을 설치해 실제로 번들을 줄이는 4단계 절차다.

1단계: 사전 버전 확인 및 next-bundle-optimizer 스킬 설치

먼저 프로젝트가 Next.js 16.4 이상(보안 패치 포함 시 16.4.5 권장)인지 확인한 뒤, skills CLI로 공식 스킬을 설치한다.

# 1. Next.js 최신 16.4.x 확인 후 공식 번들 최적화 스킬 추가
npx skills add vercel/next.js --skill next-bundle-optimizer

# 2. 스킬 파일 설치 확인
ls -la .claude/skills/next-bundle-optimizer/SKILL.md

2단계: 에이전트에서 진단 리포트 생성 (/next-bundle-optimizer)

Claude Code나 Cursor 등 Agent Skills를 지원하는 에이전트 창에서 스킬을 호출해 먼저 코드를 고치지 않고 진단 리포트와 베이스라인 스냅샷만 뽑도록 지시한다.

# 진단 모드 실행 (코드 수정 없이 모듈 그래프 분석 및 Top 5 감량 타깃 도출)
/next-bundle-optimizer

대상 라우트는 /dashboard 와 /editor 두 곳이야.
현재 클라이언트 JS 청크 스냅샷을 저장하고, 초기 번들 크기를 가장 많이 차지하는 상위 5개 원인과 import 경로 사슬을 표로 정리해줘.

3단계: 정적 Import 사슬 분리 및 컴포넌트 경계 수정 (/next-bundle-optimizer fix)

리포트에서 확인된 항목 중 안전한 수정 대상을 지정해 리팩토링을 수행하게 한다. 예를 들어 무거운 코드 에디터 모듈에서 상수만 빼내 별도 파일로 분리하는 전형적인 수정 코드는 다음과 같다.

// ❌ 수정 전: components/CodePreviewModal.tsx (dynamic import를 썼지만 정적 import가 섞인 상태)
"use client";
import dynamic from "next/dynamic";
// 아래 한 줄의 정적 import 때문에 Monaco 관련 무거운 의존성이 초기 번들에 딸려 들어옴!
import { DEFAULT_EDITOR_THEME } from "./MonacoEditorCore";

const MonacoEditorCore = dynamic(() => import("./MonacoEditorCore"), {
  ssr: false,
});
// ✅ 수정 후: 상수/타입을 경량 파일(editor-constants.ts)로 분리해 지연 로딩 복원
"use client";
import dynamic from "next/dynamic";
import { DEFAULT_EDITOR_THEME } from "./editor-constants";

const MonacoEditorCore = dynamic(() => import("./MonacoEditorCore"), {
  ssr: false,
});

4단계: 수정 전후 스냅샷 및 Lighthouse 지표 대조

코드가 변경되면 에이전트는 다시 Turbopack 분석기를 실행해 이전 스냅샷 JSON과 새 스냅샷 JSON을 비교한다.

비교 항목확인 위치판단 기준
라우트별 초기 전송 JS수정 전후 스냅샷대상 라우트의 Initial JS가 실제로 줄었는가
공유 청크에 포함된 모듈 수Turbopack 모듈 그래프무거운 모듈이 지연 청크로 옮겨졌는가
모바일 TBT(Total Blocking Time)Lighthouse같은 조건에서 여러 번 측정해 중앙값을 비교했는가

감소 폭은 프로젝트마다 다르므로 수정 전 베이스라인을 직접 측정하고, 수정 후 값과 함께 PR 설명에 남긴다.

주의점: 에이전트가 제안한 번들 최적화를 그대로 믿지 않고 검증하는 절차

에이전트는 바이트 수치를 줄이는 데 집중하기 때문에, 때로는 사용자 경험(UX)이나 런타임 안정성을 해치는 과격한 코드 분할을 제안할 수 있다. 따라서 PR을 머지하기 전에 반드시 다음 세 가지를 스냅샷과 브라우저에서 교차 검증해야 한다.

  1. 초기 화면(Above the Fold) 컴포넌트의 과도한 dynamic 분리 경계: 페이지에 접속하자마자 바로 보여야 하는 헤더나 히어로 영역까지 ssr: false 동적 임포트로 바꾸면 JS 크기는 줄어들지 몰라도 화면이 깜빡이거나 LCP(Largest Contentful Paint)와 CLS 지표가 오히려 나빠진다.
  2. 스냅샷 Diff에서 총합(Total)이 아닌 초기 로드(Initial Load) 확인: 청크만 잘게 쪼개지고 페이지 진입 시 결국 그 청크들을 동시에 다 받아온다면 실제 네트워크 이득은 없다. 스냅샷 비교에서 해당 라우트의 Initial JS 크기가 실제로 줄었는지 확인한다.
  3. 배럴 파일(index.ts) 제거 후 외부 패키지 import 경로 깨짐 확인: 모노레포 내부 공용 UI 패키지의 index.ts를 쪼갰을 때 다른 앱의 빌드가 깨지지 않는지 전체 워크스페이스 타입 체크(tsc --noEmit)를 돌린다.

초보자가 자주 실수하는 포인트

  • 모든 컴포넌트를 dynamic()으로 감싸면 좋다고 생각하는 실수: 작은 버튼이나 텍스트 컴포넌트까지 동적 청크로 쪼개면 HTTP 요청 수만 늘어나고 번들 로더 오버헤드가 커진다. 모달, 차트, 리치 텍스트 에디터처럼 초기 화면에 보이지 않거나 용량이 큰 모듈에만 적용해야 한다.
  • 아이콘 라이브러리나 유틸리티를 루트 경로에서 통째로 가져오는 습관: Next.js의 optimizePackageImports가 많은 패키지를 자동 처리해 주지만, 자체 제작한 사내 배럴 파일(src/components/index.ts)은 모듈 그래프를 한 덩어리로 묶어버리는 주범이 되므로 직접 파일 경로로 import하는 편이 안전하다.

체크리스트

  • 프로젝트가 Next.js 16.4 이상이며 Turbopack 기반으로 빌드/분석이 실행되는가?
  • 코드 수정 전에 /next-bundle-optimizer로 베이스라인 스냅샷을 먼저 생성했는가?
  • 에이전트가 dynamic(..., { ssr: false })를 추가한 컴포넌트가 검색 엔진 색인(SEO)이나 초기 LCP 영역에 해당하지 않는지 확인했는가?
  • 수정 후 생성된 스냅샷 비교표에서 라우트별 Initial JS 크기 감소와 E2E 렌더링 정상 동작을 모두 확인했는가?

자주 묻는 질문

아직 Webpack 설정(--webpack)을 유지 중인 Next.js 프로젝트에서도 이 스킬을 쓸 수 있나요?

next-bundle-optimizer 스킬의 핵심 진단 기능은 Turbopack이 출력하는 모듈·청크 그래프를 기반으로 동작한다. Webpack 빌드에서의 지원 범위는 스킬 문서를 먼저 확인한다.

CI 파이프라인에 이 스킬을 붙여서 번들 크기가 커지면 PR을 자동으로 막을 수 있나요?

스킬 문서에서 비대화형 실행 방법을 확인한 뒤 구성한다. CI에서는 에이전트가 코드를 직접 고치게 하기보다, 헤드리스 모드로 스냅샷 비교만 실행해 특정 라우트의 Initial JS가 기준치(예: +20KB) 이상 증가했을 때 어떤 import 경로 때문인지 PR 코멘트로 리포트를 남기도록 구성하면 효과적이다.

참고 자료 · 검증 기준

위 자료와 내용을 대조한 날짜: . 도구·서비스 정책은 이후 바뀔 수 있으므로 적용 전 공식 문서를 다시 확인하세요.

이 글은 실제 실무 환경 테스트 및 검증된 기술 자료를 바탕으로 작성되었으며, 환경 변화에 따라 지속적으로 갱신됩니다.