Turbopack

김동현·2026년 3월 5일
docsnext.js

next.js 공식문서 번역

목록 보기
39/79

Turbopack(터보팩)은 JavaScript와 TypeScript에 최적화된 점진적 번들러(incremental bundler)예요. Rust(러스트) 언어로 작성되었고, Next.js 안에 아예 내장되어 있죠. 여러분은 Pages 라우터와 App 라우터 모두에서 터보팩을 사용해 훨씬 더 빠른 로컬 개발 환경을 경험할 수 있습니다.

💡 강사의 보충 설명: > 여기서 '점진적(incremental)'이라는 말이 중요한데요, 코드를 수정했을 때 처음부터 모든 걸 다시 빌드하는 게 아니라 바뀐 부분만 쏙쏙 골라서 빠르게 업데이트한다는 뜻이에요. 게다가 Rust 언어는 기존 JavaScript 기반 도구(예: Webpack)보다 실행 속도가 압도적으로 빠르기 때문에 개발 생산성이 엄청나게 올라갑니다!

왜 Turbopack을 써야 할까요? (Why Turbopack?)

우리가 Next.js의 성능 한계를 끌어올리기 위해 터보팩을 만든 이유는 다음과 같아요:

  • 통합된 그래프 (Unified Graph): Next.js는 여러 출력 환경(예: 클라이언트와 서버)을 지원해요. 이럴 때 여러 개의 컴파일러를 관리하고 번들들을 꿰매어 합치는 작업은 꽤나 지루하고 번거롭죠. 터보팩은 모든 환경을 아우르는 단일하고 통합된 그래프를 사용해서 이 문제를 해결했어요.
  • 번들링 vs 네이티브 ESM (Bundling vs Native ESM): 일부 개발 도구(예: Vite 등)는 개발 환경에서 번들링을 아예 건너뛰고 브라우저의 네이티브 ESM(ECMAScript Modules) 기능에 의존해요. 이 방식은 작은 앱에서는 아주 잘 동작하지만, 앱 규모가 커지면 네트워크 요청이 너무 많아져서 오히려 느려질 수 있죠. 반면에 터보팩은 개발 환경에서도 번들링을 수행하지만, 대규모 앱에서도 속도를 유지할 수 있도록 아주 고도로 최적화된 방식을 사용해요.
  • 점진적 연산 (Incremental Computation): 터보팩은 여러 CPU 코어를 활용해 병렬로 작업을 처리하고, 연산 결과를 함수 단위까지 잘게 쪼개어 캐싱(저장)해요. 한 번 끝낸 작업은? 터보팩은 절대 똑같은 작업을 두 번 반복하지 않습니다.
  • 지연 번들링 (Lazy Bundling): 터보팩은 개발 서버에서 '실제로 요청된' 것들만 번들링해요. 이런 게으른(?) 접근 방식 덕분에 초기에 코드를 컴파일하는 시간과 메모리 사용량을 확 줄일 수 있답니다.

🔥 강사의 실무 팁: > '지연 번들링'을 실제로 체감해보면 이렇습니다. npm run dev를 쳤을 때 서버가 켜지는 속도는 미친 듯이 빠릅니다. 그런데 특정 페이지에 처음 접속할 때는 아주 살짝 로딩이 걸릴 수 있어요. 왜냐하면 여러분이 그 페이지에 접속하는 '그 순간'에 해당 페이지에 필요한 요소들만 잽싸게 번들링하기 때문이죠. 메모리를 아끼는 아주 똑똑한 방법입니다!

시작하기 (Getting started)

이제 터보팩은 Next.js의 기본 번들러입니다. 터보팩을 쓰기 위해 따로 설정할 건 아무것도 없어요:

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start"
  }
}

그래도 Webpack을 사용해야 한다면

터보팩 대신 기존의 Webpack(웹팩)을 꼭 사용해야 하는 상황이라면, --webpack 플래그를 추가해서 선택적으로 사용할 수 있습니다:

{
  "scripts": {
    "dev": "next dev --webpack",
    "build": "next build --webpack",
    "start": "next start"
  }
}

💡 강사의 보충 설명: > 아직 생태계의 모든 플러그인이 터보팩을 지원하지는 않아요. 만약 회사 프로젝트나 개인 프로젝트에서 아주 오래되거나 특수한 웹팩 플러그인을 쓰고 있다면, 이 방법으로 웹팩으로 돌아가야 할 수도 있습니다.

지원하는 기능들 (Supported features)

Next.js 환경에서의 터보팩은 일반적인 사용 사례에서는 설정이 전혀 필요 없는(zero-configuration) 상태로 동작합니다. 아래는 기본적으로 지원되는 기능들을 요약한 표이고, 필요할 때 터보팩을 추가로 설정할 수 있는 참조 링크들도 함께 제공해 드릴게요.

언어 기능 (Language features)

기능 (Feature)상태 (Status)참고 사항 (Notes)
JavaScript & TypeScript지원됨내부적으로 SWC를 사용합니다. 단, 터보팩이 타입 검사(Type-checking)까지 해주지는 않아요. 타입 검사는 tsc --watch를 실행하거나 VSCode 같은 IDE의 기능에 의존해야 합니다.
ECMAScript (ESNext)지원됨터보팩은 최신 ECMAScript 기능들을 지원하며, SWC의 지원 범위와 일치합니다.
CommonJS지원됨require() 문법은 기본적으로 알아서 처리됩니다.
ESM지원됨정적(static) 및 동적(dynamic) import 모두 완벽하게 지원됩니다.
Babel지원됨Next.js 16부터는 Babel 설정 파일이 감지되면 터보팩이 자동으로 Babel을 사용합니다. 웹팩과 다른 점은, Next.js 내부 변환이나 구형 ECMAScript 버전으로 낮추는 작업(downleveling)에는 항상 SWC가 사용된다는 점이에요. (웹팩 환경의 Next.js는 Babel 설정이 있으면 SWC를 아예 꺼버리거든요.) node_modules 폴더 안의 파일들은 여러분이 babel-loader를 수동으로 설정하지 않는 한 Babel 변환에서 제외됩니다.

프레임워크 및 React 기능 (Framework and React features)

기능 (Feature)상태 (Status)참고 사항 (Notes)
JSX / TSX지원됨SWC가 JSX/TSX 컴파일을 처리합니다.
Fast Refresh (빠른 새로고침)지원됨아무 설정도 필요 없습니다.
React Server Components (RSC)지원됨Next.js App 라우터용 기능이죠. 터보팩은 서버와 클라이언트 번들링이 정확하게 이루어지도록 보장합니다.
루트 레이아웃(Root layout) 생성지원 안 됨App 라우터에서 루트 레이아웃을 '자동'으로 만들어주는 기능은 지원하지 않아요. 대신 터보팩이 콘솔에 수동으로 직접 만들라고 안내해 줄 겁니다.

CSS 및 스타일링 (CSS and styling)

기능 (Feature)상태 (Status)참고 사항 (Notes)
글로벌 CSS지원됨애플리케이션 안에서 .css 파일을 직접 import 할 수 있습니다.
CSS Modules지원됨.module.css 파일이 네이티브하게 동작합니다. (Lightning CSS 기반)
CSS 중첩 (Nesting)지원됨Lightning CSS가 최신 CSS 중첩 문법을 지원합니다.
@import 문법지원됨여러 개의 CSS 파일을 하나로 합칠 수 있습니다.
PostCSS지원됨Node.js 워커 풀을 사용해 postcss.config.js를 자동으로 처리합니다. Tailwind나 Autoprefixer 같은 걸 쓸 때 아주 유용하죠.
Sass / SCSS지원됨 (Next.js)Next.js 환경에서는 Sass가 기본 지원됩니다. 하지만 sassOptions.functions을 이용한 '커스텀 Sass 함수'는 지원하지 않아요. 웹팩은 Node.js 환경에서 동작해서 자바스크립트 함수를 실행할 수 있지만, 터보팩은 Rust 기반 아키텍처라 자바스크립트 함수를 직접 실행할 수 없기 때문이죠. 이 기능이 꼭 필요하다면 웹팩을 쓰셔야 합니다. 나중에 터보팩을 Next.js 없이 단독으로 쓸 때는 로더 설정이 필요해질 가능성이 높습니다.
Less플러그인을 통한 지원 예정아직 기본적으로는 지원하지 않습니다. 추후 커스텀 로더 기능이 안정화되면 로더 설정을 통해 지원될 예정입니다.
Lightning CSS사용 중CSS 변환을 담당합니다. 단, 독립적인 가상 클래스로서의 :local / :global 같이 사용 빈도가 낮은 일부 CSS Modules 기능들은 아직 지원되지 않아요. 아래의 '지원되지 않는 기능' 섹션을 참고해 주세요.

🔥 강사의 실무 팁: > 요즘은 Tailwind CSS를 많이 쓰기 때문에 PostCSS 자동 지원이 매우 꿀 같은 기능입니다. 그리고 Sass 커스텀 함수 제약 부분은 꼭 기억해두세요. 회사에서 기존 레거시 코드를 마이그레이션 할 때 저 부분 때문에 터보팩을 당장 도입하지 못하는 경우가 꽤 있습니다.

에셋 처리 (Assets)

기능 (Feature)상태 (Status)참고 사항 (Notes)
정적 에셋 (이미지, 폰트)지원됨import img from './img.png' 처럼 불러오는 방식이 별도 설정 없이 바로 동작합니다. Next.js에서는 <Image /> 컴포넌트에 넣을 수 있는 객체를 반환해줘요.
JSON Imports지원됨.json 파일에서 이름 없는(default) import나 이름을 지정한(named) import 모두 지원됩니다.

모듈 해석 (Module resolution)

기능 (Feature)상태 (Status)참고 사항 (Notes)
경로 별칭 (Path Aliases)지원됨Next.js의 기존 동작과 똑같이 tsconfig.json의 paths와 baseUrl 설정을 읽어옵니다.
수동 별칭 (Manual Aliases)지원됨next.config.js에서 resolveAlias를 설정할 수 있습니다. (웹팩의 webpack.resolve.alias와 비슷해요.)
커스텀 확장자 (Custom Extensions)지원됨next.config.js에서 resolveExtensions를 설정하여 모듈을 찾을 때 사용할 파일 확장자를 바꾸거나 추가할 수 있습니다.
AMD부분적으로 지원됨기본적인 변환은 동작하지만, 복잡한 형태의 AMD 사용은 제한적입니다. (요즘은 거의 ESM을 쓰니 크게 걱정 안 하셔도 됩니다!)

성능 및 빠른 새로고침 (Performance and Fast Refresh)

기능 (Feature)상태 (Status)참고 사항 (Notes)
빠른 새로고침 (Fast Refresh)지원됨자바스크립트, 타입스크립트, CSS를 수정했을 때 브라우저 전체 새로고침 없이 변경사항만 싹 업데이트 해줍니다.
점진적 번들링 (Incremental Bundling)지원됨개발 서버가 요청하는 것들만 지연(lazy) 빌드하기 때문에, 앱 규모가 커도 속도가 엄청나게 빠릅니다.

웹팩과의 알려진 차이점 (Known gaps with webpack)

기존 프로젝트를 터보팩으로 마이그레이션(이동)할 때 알아두어야 할 웹팩과 터보팩 사이의 꽤나 큰 동작 차이들이 몇 가지 있습니다. (물론 아예 새로 만드는 앱이라면 크게 신경 쓰지 않으셔도 됩니다.)

파일 시스템 루트 (Filesystem Root)

터보팩은 모듈을 찾을 때 프로젝트의 루트 디렉토리를 기준으로 삼습니다. 그래서 프로젝트 루트 바깥에 있는 파일들은 기본적으로 찾지 못해요.

예를 들어, npm link, yarn link, pnpm link 등을 사용해서 프로젝트 폴더 밖의 종속성(dependencies)을 연결해 놓았다면, 기본 설정으로는 그 연결된 파일들을 불러올 수 없습니다. 이 파일들을 제대로 불러오려면 루트 설정을 프로젝트와 연결된 종속성들을 모두 포함하는 상위 디렉토리로 변경해 주어야 합니다.

이 설정은 next.config.js 파일의 turbopack.root 옵션을 통해 변경할 수 있어요.

💡 강사의 보충 설명: > 요즘 프론트엔드 진영에서 유행하는 '모노레포(Monorepo)' 구조를 쓸 때 이 문제가 종종 발생합니다. 터보팩이 옆 동네(다른 패키지) 코드를 못 읽어온다면 이 turbopack.root 설정을 꼭 확인해 보세요!

CSS Module 순서 (CSS Module Ordering)

터보팩은 명시적으로 순서가 정해져 있지 않은 CSS 모듈들을 정렬할 때, 자바스크립트의 import 순서를 그대로 따릅니다. 예를 들어볼까요?

import utilStyles from './utils.module.css'
import buttonStyles from './button.module.css'

export default function BlogPost() {
  return (
    <div className={utilStyles.container}>
      <button className={buttonStyles.primary}>Click me</button>
    </div>
  )
}

이 예제에서 터보팩은 생성된 CSS 묶음(chunk) 안에서 반드시 utils.module.css 내용이 button.module.css 내용보다 먼저 나오도록 import 순서를 보장합니다.

웹팩도 일반적으로는 이렇게 동작하지만, 가끔 JS 파일에 사이드 이펙트(side-effect)가 없다고 스스로 판단하면 JS에서 의도한 import 순서를 무시해버리는 경우가 있습니다.

그래서 웹팩을 쓰다가 터보팩으로 넘어왔을 때, 이전 코드들이 이런 임의의 순서에 의존하고 있었다면 미묘하게 스타일 렌더링이 깨지는 현상이 발생할 수 있어요. 해결책은 보통 간단합니다. button.module.css 파일 안에서 @import utils.module.css를 선언해서 강제로 순서를 잡아주거나, 아예 서로 충돌하는 CSS 규칙들을 수정해서 같은 속성을 건드리지 않게 만드는 것이죠.

Sass의 node_modules import (Sass node_modules imports)

터보팩은 node_modules 안에 있는 Sass 파일을 불러오는 걸 기본적으로 지원해요. 하지만 웹팩에서 쓰던 옛날 방식인 틸드(~) 문법은 터보팩에서는 지원하지 않습니다.

따라서 아래처럼 바꿔주셔야 해요.

변경 전 (웹팩 방식):

@import '~bootstrap/dist/css/bootstrap.min.css';

변경 후 (터보팩 방식):

@import 'bootstrap/dist/css/bootstrap.min.css';

만약 써드파티 라이브러리 내부 등 내가 직접 코드를 수정할 수 없는 상황이라면, next.config.js에 turbopack.resolveAlias 설정을 추가해서 ~ 문법을 실제 경로로 매핑해주는 꼼수를 쓸 수 있습니다:

module.exports = {
  turbopack: {
    resolveAlias: {
      '~*': '*',
    },
  },
}

빌드 캐싱 (Build Caching)

웹팩은 빌드 속도를 높이기 위해 디스크 빌드 캐싱 기능을 지원하죠. 터보팩도 비슷한 기능을 제공하는데 현재는 베타 버전입니다. Next.js 16부터는 아래의 실험적(experimental) 플래그를 설정해서 터보팩의 파일 시스템 캐시를 켤 수 있어요:

알아두면 좋은 정보: 이런 이유 때문에 웹팩과 터보팩의 빌드 속도를 공정하게 비교(콜드 빌드)하고 싶다면, 빌드하기 전에 반드시 .next 폴더를 지워야 합니다. 아니면 터보팩 파일 시스템 캐시 기능을 켜서 캐시가 적용된 상태(웜 빌드)끼리 비교하셔야 해요.

🔥 강사 팁: > 프론트엔드 개발하다가 '어? 코드는 완벽한데 왜 반영이 안 되지? 왜 이상한 에러가 나지?' 싶을 때 있죠? 그럴 땐 일단 서버 끄고 .next 폴더를 과감하게 삭제한 다음 다시 실행해 보세요. 캐시가 꼬여서 발생하는 문제의 90%는 이걸로 해결됩니다!

웹팩 플러그인 (Webpack plugins)

터보팩은 웹팩 플러그인을 지원하지 않습니다. 이게 꽤 중요한 점인데요. 웹팩의 플러그인 생태계에 의존하는 서드파티 도구들은 터보팩에서 작동하지 않는다는 뜻이죠. 대신 웹팩 로더(webpack loaders)는 지원하고 있습니다. 만약 여러분의 프로젝트가 특정 웹팩 플러그인에 강하게 묶여 있다면, 터보팩과 호환되는 대체재를 찾거나 터보팩에 해당 기능이 추가될 때까지는 계속 웹팩을 사용하셔야 합니다.

지원되지 않거나 계획에 없는 기능들 (Unsupported and unplanned features)

일부 기능들은 아직 구현되지 않았거나 아예 구현할 계획이 없습니다:

  • 예전 방식의 CSS Modules 기능들 (Legacy CSS Modules features)
    • 독립적인 :local 과 :global 가상 클래스는 지원 안 함 (단, :global(...) 처럼 함수 형태는 지원해요).
    • @value 규칙 (이제는 CSS variables로 대체되었기 때문).
    • :import 와 :export ICSS 규칙.
    • .module.css 안에서 일반 .css 파일을 composes (상속)하는 것. 웹팩은 불러온 일반 .css 파일도 CSS 모듈처럼 취급해 줬지만, 터보팩에서는 일반 .css는 무조건 전역(global) CSS로 취급됩니다. 따라서 composes를 쓰고 싶다면 타겟 파일의 확장자도 .module.css로 바꿔야 합니다.
    • 위와 같은 이유로 CSS Module 안에서 @import를 써서 일반 .css를 불러오는 것도 지원되지 않습니다. 타겟 파일을 .module.css로 바꿔주세요.
  • sassOptions.functions
    sassOptions.functions에 정의된 커스텀 Sass 함수는 지원하지 않습니다. 아까 위에서 설명해 드린 대로, Node.js 기반인 웹팩과 달리 Rust 기반인 터보팩 아키텍처는 자바스크립트 함수를 직접 실행할 수 없기 때문이에요. 이 기능이 꼭 필요하다면 터보팩 대신 웹팩을 사용해야 합니다.
  • next.config.js 안의 webpack() 설정
    터보팩은 웹팩을 아예 '대체'하는 거라서, 기존에 쓰던 webpack() 설정 코드는 무시됩니다. 대신 turbopack 설정을 사용해 주세요.
  • Yarn PnP (Plug'n'Play)
    Next.js 내의 터보팩에서는 이 기능을 지원할 계획이 없습니다.
  • experimental.urlImports
    터보팩에서는 지원할 계획이 없습니다.
  • experimental.esmExternals
    계획 없습니다. 터보팩은 Next.js의 옛날 방식인 esmExternals 설정을 지원하지 않습니다.
  • 일부 Next.js 실험적 플래그들 (Experimental Flags)
    • experimental.nextScriptWorkers
    • experimental.sri.algorithm
    • experimental.fallbackNodePolyfills
      이 항목들은 나중에(미래에) 구현할 계획은 있습니다.

각 기능별 상세한 플래그 상태가 궁금하시다면 터보팩 API 레퍼런스 문서를 확인해 보세요.

설정하기 (Configuration)

터보팩은 next.config.js (또는 next.config.ts) 파일 안에서 turbopack 이라는 키를 통해 설정할 수 있습니다. 가능한 옵션들은 다음과 같아요:

  • rules
    파일 변환을 위해 웹팩 로더를 추가로 정의할 때 사용합니다.
  • resolveAlias
    수동으로 경로 별칭(alias)을 만듭니다. (웹팩의 resolve.alias와 똑같은 역할입니다)
  • resolveExtensions
    모듈을 해석할 때 찾을 파일 확장자의 순서나 종류를 변경, 추가합니다.
module.exports = {
  turbopack: {
    // 예시: alias와 커스텀 파일 확장자 추가하기
    resolveAlias: {
      underscore: 'lodash',
    },
    resolveExtensions: ['.mdx', '.tsx', '.ts', '.jsx', '.js', '.json'],
  },
}

더 다양하고 깊이 있는 설정 예시를 보시려면 터보팩 설정 문서를 참고하세요.

성능 디버깅을 위한 추적(trace) 파일 생성하기

개발 중에 터보팩의 성능이나 메모리 관련해서 이상한 문제가 발생했는데 이를 Next.js 팀에 제보해서 해결에 도움을 주고 싶다면, 개발 서버 실행 명령어 앞에 NEXT_TURBOPACK_TRACING=1 환경 변수를 붙여서 추적 파일을 만들 수 있습니다:

NEXT_TURBOPACK_TRACING=1 next dev

이렇게 하면 .next/dev/trace-turbopack 경로에 파일이 하나 생성됩니다. Next.js GitHub 저장소에 이슈(Issue)를 올릴 때 이 파일을 첨부해 주시면, 개발팀이 원인을 파악하는 데 큰 도움이 됩니다.

참고로 개발 서버의 기본 출력 폴더는 .next/dev 입니다. 더 자세한 내용은 isolatedDevBuild 문서를 읽어보세요.

요약 (Summary)

터보팩(Turbopack)은 Rust 기반의 점진적(incremental) 번들러로, 로컬 개발과 빌드 속도를 미친 듯이 빠르게 만들기 위해 탄생했습니다—특히 덩치가 엄청나게 큰 앱에서 빛을 발하죠. Next.js에 기본 내장되어 있으며, 별도의 설정 없이도 CSS, React, 그리고 TypeScript를 완벽하게 지원합니다.

버전 변경 사항 (Version Changes)

버전 (Version)변경 사항 (Changes)
v16.0.0터보팩이 Next.js의 기본 번들러가 되었습니다. Babel 설정 파일이 있으면 자동으로 Babel을 지원합니다.
v15.5.0터보팩 build 기능 베타(beta) 지원 시작
v15.3.0build 기능 실험적(Experimental) 지원 시작
v15.0.0터보팩 dev (개발 서버) 기능 안정화(stable) 완료
profile
김동현
프론트에_가까운_풀스택_개발자
이전 포스트

How to set up Vitest with Next.js

다음 포스트

Edge Runtime

0개의 댓글