Communitygithub.com

next-cache-components-adoption

Next.js 앱에서 Cache Components를 활성화하고 이를 가로막는 라우팅 문제를 해결합니다. 사용자가 Cache Components를 활성화, 도입 또는 마이그레이션하고자 할 때 사용합니다.

next-cache-components-adoption란 무엇인가요?

이 스킬은 Next.js 앱에서 `cacheComponents` 플래그를 켜고 빌드가 통과할 때까지 각 라우트를 단계별로 수정하는 자동화된 프로세스를 제공합니다. 개발자는 Incremental(단계적) 또는 Direct(직접) 전략 중 하나를 선택할 수 있습니다. Incremental 방식은 먼저 codemod를 실행하여 모든 라우트에 `export const instant = false`를 추가해 검증 오류를 침묵시키고, 이후 하나씩 opt-out을 제거하며 각 라우트를 올바르게 채택합니다. Direct 방식은 바로 `cacheComponents`를 활성화하고 빌드가 실패하는 첫 번째 라우트부터 수정합니다. 이 스킬은 `next dev`와 `next build`를 모두 활용하며, `next-dev-loop` 스킬과 브라우저를 통한 런타임 검증을 강력히 권장합니다. 주요 차단 요소는 요청 시간 데이터 읽기(cookies, headers, params 등), 동기 I/O(new Date, Math.random 등), 그리고 `"use cache"` 파일에서의 잘못된 내보내기입니다.

지원 대상✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/0n6k4v-Coder/skills/tree/HEAD/next.js/next-cache-components-adoption

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

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-false codemod)이 포함됩니다. 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-false codemod는 이들을 건드리지 않습니다.

  • 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" 함수로 래핑된 읽기는 캐시 경계로 간주되며 차단 읽기가 아닙니다.

세 가지 클래스의 차단 요소가 이 순서로 에이전트에게 문제를 일으킵니다:

  1. 요청 시간 읽기 (cookies(), headers(), await params, await searchParams). 네 가지 모두 페이지나 레이아웃의 최상위에서 await될 때 차단됩니다. params와 searchParams는 쿠키나 헤더처럼 "요청 데이터"로 간주되지 않아 자주 놓칩니다. 해결 방법은 읽기를 <Suspense>로 감싸진 자식 컴포넌트로 이동하는 것입니다. params/searchParams의 경우, Promise를 자식으로 전달하고 거기서 await하세요. 페이지 최상위에서 await하지 마세요.
  2. 모듈/렌더링 시간의 동기 I/O (new Date(), Date.now(), Math.random(), crypto.randomUUID()). 이들은 instant = false에서도 빌드에 실패합니다 — opt-out이 이를 억제하지 않습니다. 공유 레이아웃에 있으면 그 아래의 모든 라우트를 차단합니다. codemod가 이를 수정할 수 없습니다. 각각을 변환해야 합니다 (안정적인 경우 "use cache"로 캐싱하거나, 요청별인 경우 await connection() + <Suspense>로 래핑) 후에 빌드가 통과할 수 있습니다. 다른 작업을 실행하기 전에 전체 저장소에서 이러한 호출을 검색하세요.
  3. 요청 데이터를 읽는 "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는 런타임 문제(스트리밍 데이터가 있는 정적 셸)입니다. 마지막에만 확인하지 말고, 각 수정 후에 확인하세요.

선호도 순서:

  1. 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 전용 개발 스크립트. 건너뛰는 경우 최종 보고서에 특정 차단 요소를 명시하세요.

  2. 직접 제어할 수 있는 브라우저. Playwright, agent-browser 직접 사용, 모든 브라우저 자동화 도구. next-dev-loop가 진정으로 차단된 경우에만 사용하세요. 프레임워크 측 검사(/_next/mcp)를 놓치므로 DOM 어설션만으로는 모든 회귀를 잡을 수 없습니다 — "확인됨"이라고 부르는 것에 대해 더 신중하세요.

  3. 빌드 전용. 개발 서버를 전혀 실행할 수 없으면 빌드가 유일한 신호입니다. <Suspense>가 없는 ○ (Static) 라우트는 빌드에 의해 완전히 확인됩니다(테스트할 스트리밍된 내용 없음). ◐ (Partial Prerender) 라우트는 셸만 확인됩니다 — 보고할 때 플래그를 지정하세요.

  4. 도구 없음. 사용자에게 개발 서버(또는 빌드)를 실행하고 결과를 보고하도록 요청하거나, 도달한 마일스톤을 커밋하고 인계하세요.

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가 수정할 수 없는 두 가지 클래스의 차단 요소를 수정하세요.

  1. 모듈/렌더링 시간의 동기 I/O. 전체 저장소에서 new Date(), Date.now(), Math.random(), crypto.randomUUID()를 검색하세요 (app/**/layout.{js,jsx,ts,tsx}뿐만 아니라 — 읽기가 레이아웃에서 가져온 모든 컴포넌트에 있을 수 있습니다). 해당하는 blocking-prerender-* 오류 카드의 해결 방법을 사용하여 각 일치 항목을 변환하세요.

  2. 호환되지 않는 세그먼트 설정. app/ 전체에서 ^export const (revalidate|dynamic|fetchCache)를 검색하고 위의 requires 참고 사항에 따라 변환하세요. codemod는 이를 건드리지 않습니다. 그대로 두면 codemod 후 빌드가 실패합니다.

codemod는 더티 작업 트리에서 실행을 거부합니다. 관련 없는 작업을 먼저 커밋하거나 스태시하거나, --force를 전달하여 편집 내용이 WIP와 함께 배치되도록 하세요. 일반적인 오탐: 최근에 Next.js를 업그레이드한 경우, package.json과 lockfile이 이미 더티 상태일 수 있습니다 — 먼저 커밋하세요.

@canary 채널을 사용하세요...

[번역본 잘림]

Individual skills in this repo

This repo contains 5 individual skills — each has its own dedicated page.

관련 스킬