next-cache-components-adoption은(는) 무엇을 하나요?
앱에서 Cache Components를 활성화하고 빌드가 통과할 때까지 단계별로 진행합니다. 이 스킬은 작업 순서를 정리하며, 오류별 해결 방법은 개발자 오버레이 수정 카드와 빌드의 터미널 출력에 있습니다. Cache Components로 마이그레이션 가이드는 이 스킬이 적용하는 개념 및 API별 해결 방법에 대한 표준 참고 자료입니다. 스킬 단계에서 패턴 ("use cache", cacheLife, <Suspense> 배치 등)을 참조할 때마다 이 가이드를 참조하여 전체 설명을 확인하세요.
요구 사항
-
App Router 프로젝트. Cache Components는 App Router 기능입니다.
cacheComponents: true는pages/라우트에서 아무런 효과가 없습니다. 프로젝트에pages/또는src/pages/트리만 있고app/또는src/app/트리가 없으면 중단하고 사용자에게 알리세요 — Pages에서 App으로의 마이그레이션은 별도 프로젝트이며, 이 스킬의 일부가 아닙니다. 하이브리드 앱 (pages/와app/가 모두 있는 경우)은 괜찮습니다. 플래그는app/라우트에만 영향을 미치며,pages/라우트는 영향을 받지 않고 opt-out이 필요하지 않습니다. -
Next.js 16.3 이상. 해당 릴리스에는 이 스킬이 의존하는 기능(최상위
cacheComponents,export const instant, 개발자 오버레이 인스턴트 네비게이션 검증 경고,cache-components-instant-falsecodemod)이 포함됩니다.next --version이 16.3 미만이면 먼저 업그레이드하세요:npx @next/codemod@latest upgrade latest를 실행하여 버전 간 codemod를 적용합니다.- codemod가 다루지 않는 내용은 관련 버전 업그레이드 가이드(예: 버전 16)를 읽으세요.
-
호환되지 않는 설정 키가 없어야 합니다.
cacheComponents: true는 여전히dynamic,revalidate또는fetchCache를 내보내는 파일에서 오류를 발생시킵니다. 삭제하지 말고 변환하세요. 각 내보내기는 라우트가 계속 수행해야 하는 동작을 인코딩합니다. 마이그레이션 가이드의 키별 섹션을 통해 각각을 Cache Components에 해당하는 방식으로 마이그레이션하세요. 값을 깔끔하게 변환할 수 없으면// TODO: Cache Components adoption — restore revalidate = 3600주석을 남겨 루프에서 처리할 수 있도록 하세요.cache-components-instant-falsecodemod는 이들을 건드리지 않습니다. -
experimental.dynamicIO는 치명적입니다. 이는 최상위cacheComponents로 이름이 변경되었으며, 이전 키는 빌드가 실행되기 전에 중단됩니다. 먼저 제거하거나cacheComponents: true로 교체하세요.experimental.useCache는 여전히 지원 중단된 별칭으로 허용됩니다.cacheComponents: true가 설정되면 중복되므로 명확성을 위해 제거하세요.
참고 사항
-
플래그 활성화 전 통과하는 기준 빌드가 없어야 합니다. 앱이 이미
"use cache"를 사용하는 경우, 플래그 활성화 전 빌드는please enable the feature flag cacheComponents오류로 실패합니다. 플래그 활성화는 (Incremental에서는 codemod 전, Direct에서는 라우트 수정 전) 가장 먼저 수행해야 할 작업입니다. 통과 빌드를 얻은 후에 수행하는 작업이 아닙니다. 시작 요약에 이를 명시하여 회귀로 오해받지 않도록 하세요. -
오프라인 문서. 가이드 링크의 오프라인 사본은
node_modules/next/dist/docs/에 있으며, 디렉토리 구조는 순서가 번호로 매겨져 있습니다 (예:node_modules/next/dist/docs/01-app/02-guides/migrating-to-cache-components.md). 끝부분 파일 이름은 슬러그와 일치합니다. 번호가 매겨진 접두사를 예측할 수 없으면find node_modules/next/dist/docs -name '<slug>.md'로 해결하세요./docs/messages/*오류 페이지는 번들에 포함되지 않습니다. 오프라인 문서가 완전히 없으면npx @next/codemod@latest agents-md를 실행하여 버전에 맞는 인덱스를AGENTS.md/CLAUDE.md에 작성하세요.
작업 구조
하나의 루프가 있습니다: 라우트 트리를 최상위에서 아래로, 한 기능씩, 각 라우트를 next dev + 브라우저에 대해 채택합니다. 빌드는 각 기능에 대한 최종 확인이지 작업 표면이 아닙니다.
1단계의 선택은 검증 오류를 먼저 침묵시킬지, 아니면 진행하면서 수정할지 결정하는 것입니다. 어느 쪽이든 루프는 동일합니다:
- 조용한 사전 단계 (Incremental). codemod를 실행하여 모든 페이지와 레이아웃을 검증에서 제외합니다. codemod가 수정할 수 없는 항목(동기 I/O 호출, 남아있는
revalidate/dynamic/fetchCache내보내기)도 함께 수정하면 빌드가 통과합니다. 이를 자체 PR로 배포한 다음 루프를 시작합니다 — 한 번에 하나의 opt-out을 제거하고 해당 라우트를 채택합니다. 작업을 작은 검토 가능한 PR로 나눕니다. - 사전 단계 없음 (Direct).
cacheComponents를 활성화하고 빌드가 먼저 플래그하는 라우트부터 루프를 시작합니다. 동일한 루프이지만, 모든 수정 사항이 채택이 완료될 때까지 하나의 브랜치에 있습니다.
두 경우 모두, 라우트별 성공 기준은 동일합니다: 개발 루프에 오류가 없고 next build가 통과해야 합니다. 각 기능 후에 사용자에게 확인하세요. 대부분의 시간을 사전 단계가 아닌 루프에서 보낼 것으로 예상됩니다.
배경
cacheComponents: true는 모든 라우트가 사전 렌더링 가능해야 함을 요구합니다. <Suspense> 외부에서 요청 시간 데이터를 읽는 라우트는 "차단"으로 간주되어 빌드에 실패합니다. export const instant = false는 라우트가 차단을 허용하도록 표시하여 개발 및 빌드 모두에서 이를 해제합니다. 레이아웃에 사용되면 그 아래의 전체 하위 트리를 포함합니다. "use cache" 함수로 래핑된 읽기는 캐시 경계로 간주되며 차단 읽기가 아닙니다.
세 가지 클래스의 차단 요소가 이 순서로 에이전트에게 문제를 일으킵니다:
- 요청 시간 읽기 (
cookies(),headers(),await params,await searchParams). 네 가지 모두 페이지나 레이아웃의 최상위에서 await될 때 차단됩니다.params와searchParams는 쿠키나 헤더처럼 "요청 데이터"로 간주되지 않아 자주 놓칩니다. 해결 방법은 읽기를<Suspense>로 감싸진 자식 컴포넌트로 이동하는 것입니다.params/searchParams의 경우, Promise를 자식으로 전달하고 거기서 await하세요. 페이지 최상위에서 await하지 마세요. - 모듈/렌더링 시간의 동기 I/O (
new Date(),Date.now(),Math.random(),crypto.randomUUID()). 이들은instant = false에서도 빌드에 실패합니다 — opt-out이 이를 억제하지 않습니다. 공유 레이아웃에 있으면 그 아래의 모든 라우트를 차단합니다. codemod가 이를 수정할 수 없습니다. 각각을 변환해야 합니다 (안정적인 경우"use cache"로 캐싱하거나, 요청별인 경우await connection()+<Suspense>로 래핑) 후에 빌드가 통과할 수 있습니다. 다른 작업을 실행하기 전에 전체 저장소에서 이러한 호출을 검색하세요. - 요청 데이터를 읽는
"use cache"파일. 최상위"use cache"지시문이 있는 파일은instant를 내보낼 수 없습니다. 둘을 결합하면Only async functions are allowed to be exported in a "use cache" file.오류가 발생하며, 이는 해당 라우트에 대해 지시문이 잘못되었음을 의미합니다. codemod를 실행하기 전에 제거하세요.
작업 표면
차단 라우트 찾기
작업 중에는 next build보다 next dev를 선호하세요.
next dev— 작업 표면입니다. 라우트를 방문하면 차단 오류가 전체 스택 추적과 오류별 문서 링크가 포함된 수정 카드와 함께 개발자 오버레이에 표시됩니다. 한 번에 하나의 라우트씩 작업하세요 — 오류가 한 곳에 누적되지 않습니다. 라우트 자체는 여전히 HTTP 200을 반환하므로 상태 코드가 아닌 오버레이 (또는.next-dev.log)를 읽으세요. 오버레이가 지워진 것은 라우트 정리의 절반입니다 — 나머지 절반은 브라우저 확인(2단계 참조)과 해당 라우트에 대한 통과 빌드입니다.next build— 감지만 합니다. 빌드는next dev의 권위 있는 확인이며 대체재가 아닙니다. 루프의 각 기능에 대한 최종 게이트(통과 빌드는 라우트별 성공 기준의 일부)로 사용하고 전체 앱에 대한 최종 확인으로 사용하세요. Incremental에서는 사전 단계(codemod가 모든 라우트를 opt-out하고, 공유 레이아웃에 동기 I/O 차단 요소가 없음)를 PR로 배송하기 전에 빌드로 확인합니다. 라우트를 작업하는 동안 빌드를 개발 루프 대신 사용하지 마세요 — 깔끔한 컴파일 오류는 정적 셸에 무엇이 포함되었고 스트리밍되었는지 알려주지 않습니다. 기본적으로 빌드는 첫 번째 차단 라우트에서 중지되므로 작업 규모를 측정하는 데에도 적합하지 않습니다. 반복할 때 도움이 되는 두 가지 플래그:--debug-build-paths는 이름을 지정한 라우트만 빌드합니다 (프로젝트 루트 기준 파일 경로의 쉼표로 구분된 glob 패턴, 예:--debug-build-paths="app/admin/**/page.tsx"— URL 경로가 아님;--debug-build-paths="app/(marketing)/about/page.tsx"—/about이 아님;--debug-build-paths="app/admin"은 아무것도 일치하지 않으며 자동으로 0개 라우트를 빌드합니다).--debug-prerender는 조기 종료를 비활성화하여 빌드가 첫 번째 사전 렌더링 실패 후에도 계속 진행되도록 하고, 모든 차단 라우트를 보고하며, 시작 파일과 줄 번호를 명명하는 더 완전한 스택 추적을 출력합니다.
모든 차단 오류에는 문서 페이지가 있습니다 — 열어보세요. 개발자 오버레이와 빌드 터미널 모두 각 오류와 함께 https://nextjs.org/docs/messages/<slug> 링크를 출력합니다. 해당 페이지는 수정에 대한 표준 해결 방법입니다. 인라인 메시지는 요약입니다. 패턴을 알고 있다고 생각하더라도, 만나는 모든 별개의 오류에 대해 링크를 가져오세요 — 해결 방법은 진화하며, 동일한 오류 클래스라도 라우트가 읽는 내용에 따라 올바른 수정 방법이 다를 수 있습니다. 인라인 메시지만으로 즉흥적으로 판단하지 마세요. (/docs/messages/* 페이지는 오프라인으로 번들에 포함되지 않습니다. 네트워크가 없으면 node_modules/next/dist/docs/ 아래의 API별 가이드로 대체하고 보고할 때 제한 사항을 명시하세요.)
런타임에 각 수정 사항 확인
통과 빌드나 지워진 오버레이는 라우트가 실제로 작동한다는 증거가 아닙니다 — Cache Components는 런타임 문제(스트리밍 데이터가 있는 정적 셸)입니다. 마지막에만 확인하지 말고, 각 수정 후에 확인하세요.
선호도 순서:
-
next-dev-loop— 강력히 권장./_next/mcp를agent-browser를 통해 라이브 브라우저와 교차 확인하고 컴파일 및 런타임 문제를 한 번에 표면화합니다. 진단(React 트리, 서스펜스 경계, 콘솔 + 네트워크)은 수동으로next dev를 찔러보는 것보다 풍부합니다.루프를 시작하기 전에 설치하세요.
next dev만으로 설명할 수 없는 문제를 만날 때까지 기다리지 마세요. 실행:npx skills add https://github.com/vercel/next.js/tree/canary/skills/next-dev-loop이 스킬은
agent-browser >= 0.27.0을 필요로 하며, 설정 과정을 안내합니다.Turbopack이 필요합니다.
package.json의dev스크립트가--webpack을 전달하면 사용자에게 플래그를 지정하고 webpack을 유지할 이유가 있는지 물어보세요. 이유가 없으면 Turbopack(Next.js 16.3+ 기본값)으로 전환하세요. webpack을 유지하려면 이 설치를 건너뛰고 빌드 전용 루프를 대신 사용하세요.next-dev-loop자체를 설치하는 데 권한이 필요하지 않습니다. 이는 dev 의존성을 설치하는 것과 같은 도구입니다. 사용자가 대기 중이면 설치 중임을 간단히 알리세요. 비대화형 실행(CI, 대시보드, 샌드박스)에서는 묻지 않고 설치하세요 — "사용자에게 프롬프트를 표시할 수 없음"은 건너뛸 이유가 아닙니다. 유일한 정당한 건너뛰기는 실제 기술적 차단 요소입니다: 네트워크 없음, npm 없음, 읽기 전용 파일 시스템, 명시된 새 의존성 금지 정책, 또는 webpack 전용 개발 스크립트. 건너뛰는 경우 최종 보고서에 특정 차단 요소를 명시하세요. -
직접 제어할 수 있는 브라우저. Playwright,
agent-browser직접 사용, 모든 브라우저 자동화 도구.next-dev-loop가 진정으로 차단된 경우에만 사용하세요. 프레임워크 측 검사(/_next/mcp)를 놓치므로 DOM 어설션만으로는 모든 회귀를 잡을 수 없습니다 — "확인됨"이라고 부르는 것에 대해 더 신중하세요. -
빌드 전용. 개발 서버를 전혀 실행할 수 없으면 빌드가 유일한 신호입니다.
<Suspense>가 없는○ (Static)라우트는 빌드에 의해 완전히 확인됩니다(테스트할 스트리밍된 내용 없음).◐ (Partial Prerender)라우트는 셸만 확인됩니다 — 보고할 때 플래그를 지정하세요. -
도구 없음. 사용자에게 개발 서버(또는 빌드)를 실행하고 결과를 보고하도록 요청하거나, 도달한 마일스톤을 커밋하고 인계하세요.
1단계: 전략 선택
사용자에게 물어보세요. PR 형태에 대한 질문으로 표현하고, 규모를 묻는 질문으로 표현하지 마세요. 내부 레이블(Incremental, Direct, 마일스톤 A)을 사용자와 대화할 때 절대 사용하지 마세요 — 이는 사용자 자신의 구조입니다. PR 및 기능 측면에서 질문하세요, 예: "Cache Components를 켜고 모든 라우트를 검증에서 제외하는 PR을 먼저 연 다음, 후속 PR에서 기능별로 실제 라우트 채택을 처리할까요? 아니면 모든 것을 하나의 브랜치에서 처리할까요?" 작은 앱에서도 Incremental 경로는 여전히 가치가 있습니다 (검토 가능한 PR 크기, 되돌리기 가능, // TODO: Cache Components adoption 마커는 다음 세션의 작업 대기열 역할). 그들을 대신하여 선택하지 마세요.
물어볼 사용자가 없으면 Incremental을 기본값으로 선택하고 그 선택을 문서화하세요.
- Incremental — 조용한 사전 단계 + 루프. codemod를 실행하여 모든 페이지와 레이아웃을 검증에서 제외하고, 빌드를 통과시키고, 중지하고 사용자와 확인한 다음(사전 단계 종료), 2단계의 루프로 진입하여 각 기능을 후속 PR로 배송합니다.
- Direct — 사전 단계 건너뛰기.
cacheComponents를 활성화하고 바로 2단계의 루프로 이동합니다. 빌드의 차단 라우트가 작업 대기열입니다.
Incremental
codemod를 호출하기 전에 codemod가 수정할 수 없는 두 가지 클래스의 차단 요소를 수정하세요.
-
모듈/렌더링 시간의 동기 I/O. 전체 저장소에서
new Date(),Date.now(),Math.random(),crypto.randomUUID()를 검색하세요 (app/**/layout.{js,jsx,ts,tsx}뿐만 아니라 — 읽기가 레이아웃에서 가져온 모든 컴포넌트에 있을 수 있습니다). 해당하는blocking-prerender-*오류 카드의 해결 방법을 사용하여 각 일치 항목을 변환하세요. -
호환되지 않는 세그먼트 설정.
app/전체에서^export const (revalidate|dynamic|fetchCache)를 검색하고 위의requires참고 사항에 따라 변환하세요. codemod는 이를 건드리지 않습니다. 그대로 두면 codemod 후 빌드가 실패합니다.
codemod는 더티 작업 트리에서 실행을 거부합니다. 관련 없는 작업을 먼저 커밋하거나 스태시하거나, --force를 전달하여 편집 내용이 WIP와 함께 배치되도록 하세요. 일반적인 오탐: 최근에 Next.js를 업그레이드한 경우, package.json과 lockfile이 이미 더티 상태일 수 있습니다 — 먼저 커밋하세요.
@canary 채널을 사용하세요...
[번역본 잘림]