라우트 세그먼트 설정

라우트 세그먼트 옵션을 사용하면 다음 변수를 직접 내보내어 페이지, 레이아웃 또는 라우트 핸들러의 동작을 구성할 수 있습니다:

옵션	타입	기본값
`experimental_ppr`	`'true' \| 'false'`
`dynamic`	`'auto' \| 'force-dynamic' \| 'error' \| 'force-static'`	`'auto'`
`dynamicParams`	`boolean`	`true`
`revalidate`	`false \| 0 \| number`	`false`
`fetchCache`	`'auto' \| 'default-cache' \| 'only-cache' \| 'force-cache' \| 'force-no-store' \| 'default-no-store' \| 'only-no-store'`	`'auto'`
`runtime`	`'nodejs' \| 'edge'`	`'nodejs'`
`preferredRegion`	`'auto' \| 'global' \| 'home' \| string \| string[]`	`'auto'`
`maxDuration`	`number`	배포 플랫폼에 의해 설정됨

옵션

`experimental_ppr`

레이아웃 또는 페이지에 대해 부분 프리렌더링 (PPR)을 활성화합니다.

layout.tsx | page.tsx

export const experimental_ppr = true;
// true | false

layout.js | page.js

export const experimental_ppr = true;
// true | false

`dynamic`

레이아웃 또는 페이지의 동적 동작을 완전히 정적 또는 완전히 동적으로 변경합니다.

layout.tsx | page.tsx | route.ts

export const dynamic = "auto";
// 'auto' | 'force-dynamic' | 'error' | 'force-static'

layout.js | page.js | route.js

export const dynamic = "auto";
// 'auto' | 'force-dynamic' | 'error' | 'force-static'

알아두면 좋은 점: app 디렉토리의 새로운 모델은 pages 디렉토리의 페이지 수준에서 getServerSideProps와 getStaticProps처럼 모든 것을 정적 또는 동적으로 처리하는 방식보다, fetch 요청 수준에서의 세분화된 캐싱 제어를 선호합니다. dynamic 옵션은 편의상 이전 모델로 다시 돌아가는 방법이며 더 간단한 마이그레이션 경로를 제공합니다.

'auto' (기본값): 컴포넌트가 동적 동작을 선택하는 것을 방지하지 않으면서 가능한 한 많이 캐시하는 기본 옵션입니다.
'force-dynamic': 동적 렌더링을 강제하여 각 사용자에 대해 요청 시 라우트가 렌더링되도록 합니다. 이 옵션은 다음과 동등합니다:
- pages 디렉토리의 getServerSideProps().
- 레이아웃 또는 페이지의 모든 fetch() 요청 옵션을 { cache: 'no-store', next: { revalidate: 0 } }로 설정.
- 세그먼트 설정을 export const fetchCache = 'force-no-store'로 설정.
'error': 동적 함수 또는 캐시되지 않은 데이터를 사용하는 컴포넌트가 있는 경우 오류를 발생시켜 레이아웃 또는 페이지의 정적 렌더링 및 데이터 캐싱을 강제합니다. 이 옵션은 다음과 동등합니다:
- pages 디렉토리의 getStaticProps().
- 레이아웃 또는 페이지의 모든 fetch() 요청 옵션을 { cache: 'force-cache' }로 설정.
- 세그먼트 설정을 fetchCache = 'only-cache', dynamicParams = false로 설정.
- dynamic = 'error'는 dynamicParams의 기본값을 true에서 false로 변경합니다. generateStaticParams에 의해 생성되지 않은 동적 매개변수에 대해 페이지를 동적으로 렌더링하려면 수동으로 dynamicParams = true를 설정하여 다시 선택할 수 있습니다.
'force-static': cookies(), headers() 및 useSearchParams()가 빈 값을 반환하도록 강제하여 레이아웃 또는 페이지의 정적 렌더링 및 데이터 캐싱을 강제합니다.

알아두면 좋은 점:

getServerSideProps와 getStaticProps에서 dynamic: 'force-dynamic'과 dynamic: 'error'로 마이그레이션하는 방법에 대한 지침은 업그레이드 가이드에서 찾을 수 있습니다.

`dynamicParams`

generateStaticParams로 생성되지 않은 동적 세그먼트를 방문할 때 어떤 일이 발생하는지 제어합니다.

layout.tsx | page.tsx

export const dynamicParams = true; // true | false,

layout.js | page.js | route.js

export const dynamicParams = true; // true | false,

true (기본값): generateStaticParams에 포함되지 않은 동적 세그먼트는 요청 시 생성됩니다.
false: generateStaticParams에 포함되지 않은 동적 세그먼트는 404를 반환합니다.

알아두면 좋은 점:

이 옵션은 pages 디렉토리의 getStaticPaths의 fallback: true | false | blocking 옵션을 대체합니다.

모든 경로를 처음 방문할 때 정적으로 렌더링하려면 generateStaticParams에서 빈 배열을 반환하거나 export const dynamic = 'force-static'을 사용해야 합니다.

dynamicParams = true일 때, 세그먼트는 스트리밍 서버 렌더링을 사용합니다.

dynamic = 'error'와 dynamic = 'force-static'이 사용되면 dynamicParams의 기본값이 false로 변경됩니다.

`revalidate`

레이아웃 또는 페이지의 기본 재검증 시간을 설정합니다. 이 옵션은 개별 fetch 요청에서 설정한 revalidate 값을 재정의하지 않습니다.

layout.tsx | page.tsx | route.ts

export const revalidate = false;
// false | 0 | number

layout.js | page.js | route.js

export const revalidate = false;
// false | 0 | number

false (기본값): cache 옵션을 'force-cache'로 설정하거나 동적 함수가 사용되기 전에 발견된 fetch 요청을 캐시하는 기본 방식입니다. 의미상 revalidate: Infinity와 동등하며, 이는 리소스가 무기한 캐시되어야 함을 의미합니다. 개별 fetch 요청은 여전히 cache: 'no-store' 또는 revalidate: 0을 사용하여 캐시를 피하고 라우트를 동적으로 렌더링할 수 있습니다. 또는 라우트 기본값보다 낮은 양수로 revalidate를 설정하여 라우트의 재검증 빈도를 높일 수 있습니다.
0: 동적 함수나 캐시되지 않은 데이터 가져오기가 발견되지 않더라도 레이아웃 또는 페이지가 항상 동적으로 렌더링되도록 합니다. 이 옵션은 cache 옵션을 설정하지 않은 fetch 요청의 기본값을 'no-store'로 변경하지만, 'force-cache'를 선택하거나 양수의 revalidate를 사용하는 fetch 요청은 그대로 둡니다.
number: (초 단위) 레이아웃 또는 페이지의 기본 재검증 빈도를 n초로 설정합니다.

알아두면 좋은 점:

revalidate 값은 정적으로 분석 가능해야 합니다. 예를 들어 revalidate = 600은 유효하지만 revalidate = 60 * 10은 유효하지 않습니다.

revalidate 값은 runtime = 'edge'를 사용할 때 사용할 수 없습니다.

재검증 빈도

단일 라우트의 각 레이아웃과 페이지에서 가장 낮은 revalidate가 전체 라우트의 재검증 빈도를 결정합니다. 이는 자식 페이지가 부모 레이아웃만큼 자주 재검증되도록 보장합니다.
개별 fetch 요청은 라우트의 기본 revalidate보다 낮은 revalidate를 설정하여 전체 라우트의 재검증 빈도를 높일 수 있습니다. 이를 통해 일부 기준에 따라 특정 라우트에 대해 더 빈번한 재검증을 동적으로 선택할 수 있습니다.

`fetchCache`

이것은 기본 동작을 특별히 재정의해야 하는 경우에만 사용해야 하는 고급 옵션입니다.

기본적으로 Next.js는 동적 함수가 사용되기 전에 도달할 수 있는 fetch() 요청을 캐시하고, 동적 함수 사용 후에 발견된 fetch 요청은 캐시하지 않습니다.

fetchCache를 사용하면 레이아웃이나 페이지의 모든 fetch 요청의 기본 cache 옵션을 재정의할 수 있습니다.

layout.tsx | page.tsx | route.ts

export const fetchCache = "auto";
// 'auto' | 'default-cache' | 'only-cache'
// 'force-cache' | 'force-no-store' | 'default-no-store' | 'only-no-store'

layout.js | page.js | route.js

export const fetchCache = "auto";
// 'auto' | 'default-cache' | 'only-cache'
// 'force-cache' | 'force-no-store' | 'default-no-store' | 'only-no-store'

'auto' (기본값): 동적 함수 이전의 fetch 요청은 제공된 cache 옵션으로 캐시하고 동적 함수 이후의 fetch 요청은 캐시하지 않는 기본 옵션입니다.
'default-cache': fetch에 어떤 cache 옵션도 전달할 수 있지만, 옵션이 제공되지 않으면 cache 옵션을 'force-cache'로 설정합니다. 이는 동적 함수 이후의 fetch 요청도 정적으로 간주됨을 의미합니다.
'only-cache': 모든 fetch 요청이 캐싱을 선택하도록 보장합니다. 옵션이 제공되지 않으면 기본값을 cache: 'force-cache'로 변경하고 cache: 'no-store'를 사용하는 fetch 요청이 있으면 오류를 발생시킵니다.
'force-cache': 모든 fetch 요청의 cache 옵션을 'force-cache'로 설정하여 모든 fetch 요청이 캐싱을 선택하도록 보장합니다.
'default-no-store': fetch에 어떤 cache 옵션도 전달할 수 있지만, 옵션이 제공되지 않으면 cache 옵션을 'no-store'로 설정합니다. 이는 동적 함수 이전의 fetch 요청도 동적으로 간주됨을 의미합니다.
'only-no-store': 모든 fetch 요청이 캐싱을 선택하지 않도록 보장합니다. 옵션이 제공되지 않으면 기본값을 cache: 'no-store'로 변경하고 cache: 'force-cache'를 사용하는 fetch 요청이 있으면 오류를 발생시킵니다.
'force-no-store': 모든 fetch 요청의 cache 옵션을 'no-store'로 설정하여 모든 fetch 요청이 캐싱을 선택하지 않도록 보장합니다. 이는 'force-cache' 옵션을 제공하더라도 모든 fetch 요청이 매 요청마다 다시 가져오도록 강제합니다.

교차 라우트 세그먼트 동작

단일 라우트의 각 레이아웃과 페이지에 걸쳐 설정된 옵션은 서로 호환되어야 합니다.
- 'only-cache'와 'force-cache'가 모두 제공되면 'force-cache'가 우선합니다. 'only-no-store'와 'force-no-store'가 모두 제공되면 'force-no-store'가 우선합니다. force 옵션은 라우트 전체의 동작을 변경하므로 'force-*'가 있는 단일 세그먼트는 'only-*'로 인한 오류를 방지할 수 있습니다.
- 'only-*'와 'force-*' 옵션의 의도는 전체 라우트가 완전히 정적이거나 완전히 동적이도록 보장하는 것입니다. 이는 다음을 의미합니다:
  - 단일 라우트에서 'only-cache'와 'only-no-store'의 조합은 허용되지 않습니다.
  - 단일 라우트에서 'force-cache'와 'force-no-store'의 조합은 허용되지 않습니다.
- 자식이 'auto' 또는 '*-cache'를 제공하는 경우 부모는 'default-no-store'를 제공할 수 없습니다. 이는 동일한 fetch가 다른 동작을 가질 수 있기 때문입니다.
일반적으로 공유 부모 레이아웃은 'auto'로 두고 자식 세그먼트가 분기되는 곳에서 옵션을 사용자 정의하는 것이 좋습니다.

`runtime`

애플리케이션 렌더링에는 Node.js 런타임을, 미들웨어에는 Edge 런타임을 사용하는 것을 권장합니다(Edge 런타임만 지원됨).

layout.tsx | page.tsx | route.ts

export const runtime = "nodejs";
// 'nodejs' | 'edge'

layout.js | page.js | route.js

export const runtime = "nodejs";
// 'nodejs' | 'edge'

'nodejs' (기본값)
'edge'

다양한 런타임에 대해 자세히 알아보세요.

`preferredRegion`

layout.tsx | page.tsx | route.ts

export const preferredRegion = "auto";
// 'auto' | 'global' | 'home' | ['iad1', 'sfo1']

layout.js | page.js | route.js

export const preferredRegion = "auto";
// 'auto' | 'global' | 'home' | ['iad1', 'sfo1']

preferredRegion 지원 여부와 지원되는 지역은 배포 플랫폼에 따라 다릅니다.

알아두면 좋은 점:

preferredRegion이 지정되지 않으면 가장 가까운 부모 레이아웃의 옵션을 상속받습니다.

루트 레이아웃은 기본적으로 all 지역으로 설정됩니다.

`maxDuration`

기본적으로 Next.js는 서버 측 로직(페이지 렌더링 또는 API 처리)의 실행을 제한하지 않습니다. 배포 플랫폼은 Next.js 빌드 출력의 maxDuration을 사용하여 특정 실행 제한을 추가할 수 있습니다. 예를 들어, Vercel에서는 이를 사용합니다.

참고: 이 설정은 Next.js 13.4.10 이상이 필요합니다.

layout.tsx | page.tsx | route.ts

export const maxDuration = 5;

layout.js | page.js | route.js

export const maxDuration = 5;

알아두면 좋은 점:

서버 액션을 사용하는 경우, 페이지 수준에서 maxDuration을 설정하여 페이지에서 사용되는 모든 서버 액션의 기본 타임아웃을 변경할 수 있습니다.

`generateStaticParams`

generateStaticParams 함수는 동적 라우트 세그먼트와 함께 사용하여 요청 시간이 아닌 빌드 시간에 정적으로 생성될 라우트 세그먼트 매개변수 목록을 정의할 수 있습니다.

자세한 내용은 API 참조를 참조하세요.

route.js template.js