Turbopack 캐시는 속도 옵션이 아니라 빌드 상태 계약이다

• 카테고리: web_app_dev
• 예상 읽기 시간: 10분
• 오늘의 질문: Next.js 빌드와 개발 서버가 더 많은 캐시를 쓰기 시작할 때, 팀은 무엇을 속도 개선으로 보고 무엇을 검증 계약으로 봐야 할까?
• 핵심 출처:
  • Turbopack: What’s New in Next.js 16.3 - 2026-06-29, 확인일 2026-07-07
  • Next.js 16.3: Instant Navigations - 2026-06-24, 확인일 2026-07-07
  • Next.js 16.3: AI Improvements - 2026-06-26, 확인일 2026-07-07
  • next.config.js: turbopack - n.d., 확인일 2026-07-07
  • vercel/next.js v16.3.0-preview.5 - 2026-06-25, 확인일 2026-07-07

1. 왜 지금 봐야 하나

Next.js 16.3 Preview의 Turbopack 글은 “더 빨라졌다”는 릴리스 노트처럼 보이지만, 웹앱 팀 입장에서는 더 중요한 신호가 있다. 빌드 도구가 점점 상태를 오래 기억하는 시스템이 되고 있다는 점이다.

공식 글은 Turbopack dev server가 incremental compilation을 위해 이전 작업을 캐시하고, 16.3에서 장시간 개발 세션의 메모리 사용을 크게 줄였다고 설명한다. 예시로 Vercel dashboard는 50개 route를 compile한 뒤 메모리가 21.5GB에서 2GB로, nextjs.org는 4.6GB에서 840MB로 줄었다고 밝혔다. 동시에 next build에도 파일 시스템 캐시를 실험적으로 제공해, nextjs.org의 compile 시간이 cold 21초에서 cached 9.2초로 줄어든 사례를 공개했다.

이 숫자만 보면 답은 쉬워 보인다. “캐시를 켜면 된다.” 하지만 실무에서는 캐시가 빠를수록 질문이 바뀐다.

• 개발 서버가 오래 살아 있을 때 어떤 상태가 메모리에 남고, 어떤 상태가 디스크로 내려가는가?
• CI에서 .next를 보존하면 어떤 입력이 바뀌었을 때 안전하게 무효화되는가?
• monorepo나 linked package를 쓰는 팀은 Turbopack의 root가 어디여야 하는가?
• AI 코딩 에이전트, IDE, type checker, browser가 동시에 뜬 로컬 환경에서 메모리 예산을 어떻게 나눌 것인가?

오늘의 핵심 문장: Turbopack 캐시는 속도 버튼이 아니라 “어떤 입력으로 만든 빌드 상태를 언제 재사용해도 되는가”를 정하는 계약이다.

2. 핵심 개념

빌드 캐시는 보통 “결과물을 저장했다가 다시 쓰는 것”으로 이해한다. 하지만 웹앱 빌드에서 캐시는 네 가지 질문의 묶음이다.

첫째, 입력 범위다. 어떤 파일, 설정, 환경변수, lockfile, loader, PostCSS 설정, alias가 빌드 결과에 영향을 주는가? Next.js Turbopack 문서는 turbopack.root가 module resolving, filesystem watching, cache validation에 영향을 준다고 설명한다. 프로젝트 root 밖의 파일을 쓰는 monorepo나 linked dependency 환경이라면, root 설정은 단순 경로 옵션이 아니라 캐시가 관찰해야 할 세계의 경계다.

둘째, 저장 위치다. 16.3 글은 Turbopack이 기존에는 CPU를 줄이기 위해 많은 중간 결과를 메모리에 잡아두는 쪽으로 설계됐지만, 이제는 파일 시스템 persistence를 활용해 메모리 cache 일부를 비우면서도 디스크에 보존할 수 있다고 설명한다. 메모리 캐시는 빠르지만 오래 켜둔 개발 서버에서 부풀 수 있고, 디스크 캐시는 느리지만 세션을 넘겨 재사용할 수 있다.

셋째, 무효화 조건이다. 좋은 캐시는 빠른 캐시가 아니라 틀렸을 때 버려지는 캐시다. next.config.ts, lockfile, loader 옵션, postcss.config, React Compiler 옵션, route graph가 바뀌었는데 이전 산출물을 계속 믿으면 빌드가 빠른 대신 디버깅이 어려워진다.

넷째, 운영 환경이다. 로컬에서는 캐시가 개발자 경험을 좌우하고, CI에서는 배포 시간과 재현성을 좌우한다. 공식 글은 CI에서 .next 디렉터리를 run 사이에 보존하면 Turbopack이 disk cache entry를 읽고 이전 작업을 재사용할 수 있다고 설명한다. 이때 CI cache key를 너무 넓게 잡으면 stale build 위험이 생기고, 너무 좁게 잡으면 매번 cold build가 된다.

3. 최신 이슈와 연결

Next.js 16.3 Preview의 흐름을 같이 보면 Turbopack 개선은 독립된 성능 뉴스가 아니다.

• Instant Navigations 글은 Cache Components, streaming, instant() Playwright helper, 느린 navigation을 dev error로 드러내는 Instant Insights를 소개한다. 즉 프레임워크가 “빠른 느낌”을 개발 중 검증 가능한 계약으로 바꾸고 있다.
• AI Improvements 글은 AGENTS.md, first-party Skills, next-dev-loop, agent browser, actionable errors를 소개한다. 즉 프레임워크가 사람뿐 아니라 AI 에이전트가 읽고 수정하고 검증할 수 있는 피드백 루프를 만들고 있다.
• Turbopack 글은 dev memory eviction, build filesystem cache, Rust React Compiler, import.meta.glob, local PostCSS config support를 소개한다. 즉 빌드 파이프라인 자체가 더 오래 기억하고, 더 많은 도구와 연결되며, 더 큰 앱에서 버티도록 바뀌고 있다.

여기서 작은 팀이 놓치기 쉬운 점은 “Preview”라는 단어다. 16.3 Preview는 써볼 가치가 있지만, production 빌드 계약으로 채택할 때는 실험 플래그의 범위를 분리해야 한다. 예를 들어 turbopackFileSystemCacheForBuild는 build 캐시를 켜는 실험 옵션이고, Rust React Compiler도 reactCompiler: true와 experimental.turbopackRustReactCompiler를 함께 켜서 실험한다. 성능 수치는 앱 구조에 따라 달라지므로 공식 사례를 우리 앱의 보장값으로 읽으면 안 된다.

4. 개발자 관점 해석

웹앱 개발자는 Turbopack 캐시를 세 단계로 나눠 봐야 한다.

A. 로컬 개발 서버: 메모리 예산의 문제

AI 코딩 에이전트가 보편화되면서 로컬 개발 환경은 더 무거워졌다. 브라우저, IDE, language server, type checker, test watcher, agent browser, MCP server가 같이 뜬다. Turbopack의 dev memory eviction은 이런 환경에서 “dev server 하나가 RAM을 다 먹지 않게 하는” 품질 개선이다.

하지만 메모리 eviction을 켠다고 모든 문제가 사라지는 것은 아니다. route를 많이 돌아다니는 QA 세션, MDX·SVG·GraphQL loader가 섞인 앱, monorepo linked package를 쓰는 앱은 여전히 관찰이 필요하다. 로컬에서 확인할 지표는 “첫 시작이 몇 초인가”보다 “2시간 뒤에도 HMR이 안정적인가”다.

B. CI build: 캐시 key와 재현성의 문제

next build 파일 시스템 캐시는 CI 시간을 줄일 수 있다. 그러나 CI cache는 팀의 배포 신뢰도와 직접 연결된다. 최소한 다음 입력은 cache key에 들어가야 한다.

• package-lock.json, pnpm-lock.yaml, yarn.lock 같은 lockfile
• next.config.*, tsconfig.json, postcss.config.*
• Node.js 버전과 package manager 버전
• React Compiler, Turbopack 실험 플래그
• monorepo라면 빌드 대상 package와 shared package의 변경 hash

처음 도입할 때는 “cache hit일 때 빠르다”만 보지 말고, 하루에 한 번 cold build를 강제로 돌려 cached build와 결과가 같은지 비교하는 편이 안전하다.

C. 설정 이관: webpack 감각을 그대로 가져오면 안 되는 문제

Turbopack 문서는 built-in CSS와 현대 JavaScript compile에 별도 webpack loader가 필요 없다고 설명한다. 반면 webpack loader compatibility에는 제한이 있다. 예를 들어 일부 loader API는 지원되지 않고, loader가 JavaScript code를 반환해야 하며, stylesheet나 image를 transform하는 loader는 현재 지원되지 않는다고 문서화되어 있다.

따라서 migration 체크리스트는 “webpack config를 Turbopack config로 옮겼나?”가 아니라 “이 loader가 Turbopack의 입력 계약 안에서 같은 산출물을 만드는가?”여야 한다.

5. 내 프로젝트에 적용할 체크포인트

오늘 바로 확인할 항목은 다음과 같다.

1. 캐시 입력 목록을 적는다. next.config, lockfile, env, PostCSS, MDX, SVG, GraphQL, alias, monorepo shared package를 표로 만든다.
2. CI cache key를 코드로 리뷰한다. .next를 보존한다면 어떤 파일 변경이 cache miss를 만드는지 PR에서 읽을 수 있어야 한다.
3. cold/cached build를 분리 측정한다. rm -rf .next 후 build와 cache 보존 build를 각각 재고, “속도 개선”과 “재현성”을 같이 기록한다.
4. long-running dev를 테스트한다. 개발 서버를 켠 뒤 route 30~50개를 이동하고, HMR 수정 10회를 반복한 뒤 메모리와 rebuild 시간을 본다.
5. monorepo root를 확인한다. linked dependency가 root 밖에 있으면 turbopack.root를 어디로 둘지 정한다. root를 넓히면 watch 범위와 cache validation 비용도 늘어난다.
6. 실험 플래그를 feature flag처럼 다룬다. turbopackFileSystemCacheForBuild, Rust React Compiler 같은 옵션은 PR 단위로 켜고 rollback 방법을 적는다.
7. AI 에이전트 작업과 연결한다. agent가 “빌드가 빠르다”고 말하는 것보다, cold build·cached build·브라우저 런타임 확인을 모두 통과했는지 로그로 남기게 한다.

6. 오늘 10분 액션

아래 10분 실험을 한 번 해보자.

# 1분: 현재 Next/Node 버전과 lockfile 확인
node -v
npm ls next react react-dom --depth=0

# 2분: cold build 시간 측정
rm -rf .next
time npm run build

# 2분: cached build 시간 측정
time npm run build

# 2분: next.config에서 Turbopack 관련 옵션 확인
# - turbopack.root
# - turbopack.rules
# - experimental.turbopackFileSystemCacheForBuild
# - experimental.turbopackRustReactCompiler

# 3분: CI 설정에서 .next cache key에 lockfile/config가 들어가는지 확인

결과를 이렇게 기록하면 충분하다.

cold build: __초
cached build: __초
cache key 입력: lockfile / next.config / node version / package manager / shared packages
의심되는 누락: __
rollback 방법: cache 삭제 / experimental flag off / cold build fallback

핵심은 “몇 초 빨라졌는가”보다 “빨라진 상태를 믿어도 되는 조건을 설명할 수 있는가”다.

7. 더 볼 자료

• Turbopack: What’s New in Next.js 16.3
• Next.js 16.3: Instant Navigations
• Next.js 16.3: AI Improvements
• Next.js next.config.js: turbopack
• vercel/next.js v16.3.0-preview.5

중복 회피 메모

로컬 content/generated와 Supabase 최근 web_app_dev 글을 확인했다. 최근 글은 Next.js 인증/streaming 경계, Server Actions POST 계약, Cache Components 데이터 신선도, React Compiler 렌더링 계약, Supabase RLS/Auth/Branching, Hono SSR와 보안 릴리스를 다뤘다. 이번 글은 Next.js를 다시 다루지만 인증·Server Actions·Cache Components·React Compiler 자체가 아니라, Next.js 16.3 Preview의 Turbopack dev memory eviction과 build file system cache를 중심으로 빌드 캐시, CI 재현성, monorepo root, AI 코딩 환경의 메모리 예산이라는 다른 관점에 집중한다.