Next.js Cache Components 마이그레이션 — route config 지우고 use cache로 옮기는 순서
Next.js 16으로 올렸는데 `export const revalidate = 3600` 같은 줄이 있던 라우트가 빌드에서 에러를 냈다면, 그게 Cache Components 마이그레이션입니다. 예전 모델은 라우트 단위 설정으로 캐싱을 정했는데, Cache Components가 켜지면 `dynamic`, `revalidate`, `fetchCache` 같은 route segment config는 사라지고, 대신 캐시할 데이터를 `'use cache'`로 직접 표시하고 수명은 `cacheLife`로 정합니다. 핵심 변화는 하나예요. 예전에는 안 캐시하겠다고 안 적으면 캐시가 됐는데, 이제는 캐시하겠다고 적지 않으면 아무것도 캐시되지 않습니다. 데이터는 기본적으로 매 요청마다 새로 가져옵니다. 이 글은 공식 마이그레이션 가이드 순서대로, 기존 앱을 한 번에 다 바꾸지 않고 안전하게 옮기는 방법입니다.
## 1. 먼저 16으로 올리고, 플래그 하나만 켠다
Cache Components는 Next.js 16이 필요합니다. 15 이하라면 버전 16 업그레이드 가이드부터 따라오세요. 16에 올라왔으면 `next.config.ts`에 한 줄만 추가합니다.
```ts
import type { NextConfig } from 'next'
const nextConfig: NextConfig = {
cacheComponents: true,
}
export default nextConfig
```
예전에 `experimental.dynamicIO`나 `experimental.useCache`를 쓰고 있었다면 이제 그 자리는 이 플래그 하나가 대신합니다. `experimental.ppr`도 Next.js 16에서 제거됐고, Partial Prerendering은 Cache Components의 일부가 됐습니다. 플래그를 켜는 순간 `dynamic`, `revalidate`, `fetchCache`를 export하고 있는 라우트는 에러가 나기 시작합니다. 그 에러가 마이그레이션 할 일 목록입니다. 개발 모드에서는 여기에 더해 "instant navigation validation"이 동작합니다. 각 라우트로 이동했을 때 바로 렌더링이 되는지 검증하고, 막히는 코드를 dev 오버레이에 에러나 인사이트로 보여줍니다.
## 2. 한 번에 다 바꾸지 않는다 — `instant = false`로 미루는 것부터
운영 중인 앱을 한 번에 다 옮기는 건 위험합니다. 공식 가이드가 권장하는 순서는 이렇습니다.
1. 플래그를 켜고, 각 route segment config를 아래 3번 표대로 교체합니다.
2. 당장 손댈 수 없는 라우트는 `instant = false`를 붙여 검증을 미룹니다.
```tsx
// app/dashboard/layout.tsx
export const instant = false
```
전체 앱을 한 번에 옵트아웃하려면 코드모드가 있습니다.
```bash
npx @next/codemod@canary cache-components-instant-false ./app
```
`src/` 프로젝트라면 `./src/app`을 넘겨야 하고, 잘못된 경로를 주면 실패 대신 `0 ok`가 나온다고 하니 파일 개수를 확인하세요. 그 다음 준비된 라우트부터 `instant = false`를 하나씩 떼면서 검증 인사이트를 해결합니다.
단, 미룰 수 없는 게 하나 있습니다. `new Date()`, `Date.now()`, `Math.random()`, `crypto.randomUUID()` 같은 동기 IO 호출은 프리렌더 중에 빌드 에러를 냅니다. `instant = false`를 붙여도 이 에러는 사라지지 않습니다. 해당 부분을 `<Suspense>`로 감싸고 `connection()`을 먼저 호출해서 요청 시점에 실행되게 하거나, 클라이언트 컴포넌트로 옮겨야 합니다. `instant = false`는 "막혀도 된다"는 표시일 뿐, 라우트를 강제로 다이나믹으로 만드는 것도 아닙니다. 진짜로 프리렌더가 가능한 라우트는 여전히 정적 셸을 냅니다.
## 3. route config 교체표 — 외울 건 이 다섯 줄
```tsx
// Before: export const dynamic = 'force-dynamic'
// After: 그냥 지웁니다. 캐시되지 않은 데이터는 원래 요청 시점에 실행되니까요.
// Before: export const dynamic = 'force-static'
// After:
import { cacheLife } from 'next/cache'
export default async function Page() {
'use cache'
cacheLife('max')
const data = await fetch('https://api.example.com/data')
return <div>...</div>
}
// Before: export const revalidate = 3600 // 1시간
// After:
export default async function Page() {
'use cache'
cacheLife('hours')
return <div>...</div>
}
// Before: export const revalidate = 0
// After: 그냥 지웁니다. 매 요청 실행이 기본값이니까요.
// Before: export const fetchCache = 'force-cache'
// After: 캐시할 데이터를 'use cache' 스코프 안에 넣습니다.
export default async function Page() {
'use cache'
// 이 안의 fetch는 캐시됩니다
return <div>...</div>
}
```
`cacheLife` 내장 프로필은 `'seconds'`, `'minutes'`, `'hours'`, `'days'`, `'weeks'`, `'max'`입니다. 기존 `revalidate` 값이 프로필과 딱 안 맞으면 가장 가까운 프로필을 고르거나 커스텀 프로필을 정의하면 됩니다. `force-static`을 쓰던 라우트에서 `cookies()`, `headers()`, `useSearchParams()` 같은 요청 시점 API가 실제 요청 값을 읽어야 한다면, 그 의존성을 없애거나 정적 유지를 포기해야 합니다. 완전히 정적인 출력이 꼭 필요한 라우트라면 16.4 이상에서 쓸 수 있는 `export const ensureStatic = 'navigation'`을 붙입니다. 선택 사항이고, 정적 출력 요구가 남아 있을 때만 추가하세요. `runtime = 'edge'`는 지웁니다. Cache Components는 Node.js 런타임이 필요합니다.
## 4. fetch와 unstable_cache는 이렇게 옮긴다
`fetch`의 `cache: 'force-cache'`와 `next: { revalidate, tags }` 옵션은 `use cache` 함수 안으로 들어갑니다.
```tsx
// Before
const res = await fetch('https://api.example.com/data', {
cache: 'force-cache',
next: { revalidate: 3600, tags: ['data'] },
})
// After
import { cacheLife, cacheTag } from 'next/cache'
async function getData() {
'use cache'
cacheLife('hours')
cacheTag('data')
const res = await fetch('https://api.example.com/data')
return res.json()
}
```
`unstable_cache`는 당장 바꿀 필요가 없습니다. Cache Components와 같이 동작하니 나중에 옮겨도 됩니다. 옮긴다면 래퍼를 풀고 `'use cache'` 지시문을 단 함수로 바꾸면 되고, 캐시 키는 인자에서 자동으로 만들어지니 키 배열은 필요 없어집니다.
```ts
// Before
import { unstable_cache } from 'next/cache'
export const getUser = unstable_cache(
async (id: string) => db.query.users.findFirst({ where: eq(users.id, id) }),
['user'],
{ tags: ['users'], revalidate: 3600 }
)
// After
import { cacheLife, cacheTag } from 'next/cache'
export async function getUser(id: string) {
'use cache'
cacheLife('hours')
cacheTag('users')
return db.query.users.findFirst({ where: eq(users.id, id) })
}
```
한 가지, 저장 위치가 다릅니다. `fetch` Data Cache와 `unstable_cache`는 배포를 넘어서, 서버리스 인스턴스를 넘어서 값을 유지합니다. 반면 `'use cache'`는 기본적으로 인메모리라서 서버리스 인스턴스가 사라지면 함께 사라지고, 배포 단위로 범위가 정해집니다. 오래 유지돼야 하는 캐시라면 `use cache: remote`나 cache handler를 쓰세요. 그래도 새 배포 뒤에는 다시 계산될 수 있다고 생각하는 게 안전합니다.
## 5. 무효화는 태그 + 용도별 API로 나눈다
캐시할 데이터에 `cacheTag`를 달아두고, 무효화는 "누가, 언제 봐야 하느냐"로 API를 나눕니다.
```ts
// Server Action에서, 내가 방금 바꾼 걸 다음 요청에서 바로 봐야 할 때
'use server'
import { updateTag } from 'next/cache'
export async function createPost(formData: FormData) {
// 글 생성 후
updateTag('posts')
}
```
- `updateTag('posts')` — Server Action에서만 호출할 수 있습니다. 다른 곳에서 부르면 에러가 납니다. 다음 요청이 stale을 보여주지 않고 새 데이터를 기다립니다. 내가 바꾼 걸 내가 바로 보는 read-your-own-writes에 씁니다.
- `revalidateTag('posts', 'max')` — Route Handler나 웹훅에서 씁니다. 두 번째 인자로 캐시 프로필이 필수입니다. `'max'`를 주면 캐시된 걸 보여주면서 뒤에서 새로고침하는 stale-while-revalidate 동작이 됩니다.
- `revalidatePath` — 이전 모델과 그대로입니다.
예전처럼 `revalidateTag('posts')`만 부르면 이제 프로필이 없어서 안 됩니다. 웹훅에서 "글을 바꿨으니 캐시를 비워줘"를 하던 코드가 있다면 두 번째 인자를 꼭 확인하세요.
## 흔한 함정 3가지
1. **`instant = false`를 영구 탈출구로 쓰는 것.** 미루는 용도지 해결이 아닙니다. 동기 IO 빌드 에러는 이걸로 안 사라지고, 라우트를 다이나믹으로 강제하지도 않습니다. 옵트아웃 목록이 줄어드는지 주기적으로 확인하세요.
2. **사용자별 데이터에 `'use cache'`를 붙이는 것.** "아무것도 캐시 안 된다"는 게 안전하다는 뜻은 아닙니다. 캐시 범위를 잘못 잡으면 한 사용자의 데이터가 다른 사용자에게 보일 수 있습니다. 개인화된 부분은 캐시 스코프 밖이나 `<Suspense>` 안에 두세요.
3. **`revalidateTag`를 옛날처럼 부르는 것.** 두 번째 인자(캐시 프로필)가 없으면 안 되고, `updateTag`는 Server Action 밖에서 부르면 에러입니다. 무효화 코드는 용도별로 나눠서 확인하세요.
## 체크리스트
- [ ] Next.js 16으로 업그레이드했나
- [ ] `next.config.ts`에 `cacheComponents: true`를 켰나
- [ ] `dynamic`, `revalidate`, `fetchCache`를 지우고 `use cache` + `cacheLife`로 바꿨나
- [ ] 당장 못 바꾸는 라우트는 `instant = false`로 미루고, 목록을 남겨뒀나
- [ ] `new Date()`, `Math.random()` 같은 동기 IO는 `<Suspense>` + `connection()`으로 옮겼나
- [ ] `fetch`의 `next.revalidate`/`next.tags`를 `cacheLife`/`cacheTag`로 옮겼나
- [ ] `unstable_cache`는 당장 둘지, 옮길지 정했나 (저장 위치 차이 확인했나)
- [ ] 무효화는 `updateTag`(Server Action, 즉시 확인)와 `revalidateTag(tag, 'max')`(웹훅, SWR)로 나눴나
- [ ] 정적 출력이 꼭 필요한 라우트에만 `ensureStatic`을 썼나 (16.4 이상, 선택 사항)
여러분은 마이그레이션할 때 한 번에 다 바꾸는 편인가요, 아니면 `instant = false`로 한 라우트씩 옮기는 편인가요? 저는 운영 중인 앱이라면 후자부터 시작합니다. 빌드가 계속 초록불인 상태로 옮기는 게, 나중에 되돌릴 때도 훨씬 쉽거든요.
0 0 1
댓글 0
로그인하고 댓글 남기기 →