Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[#52] docs: incremental-static-regeneration 번역 #99

Merged
merged 4 commits into from
Aug 5, 2024
Merged

[#52] docs: incremental-static-regeneration 번역 #99

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
bd80705
[#31] docs: custom-error 번역
imdaxsz Jul 29, 2024
9f490cd
[#31] style: prettier 적용
imdaxsz Jul 30, 2024
4421308
Merge remote-tracking branch 'upstream/main'
imdaxsz Jul 31, 2024
f89d1c8
[#52] docs: incremental-static-regeneration 번역
imdaxsz Aug 4, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
120 changes: 59 additions & 61 deletions ...ges/building-your-application/data-fetching/incremental-static-regeneration.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,24 +3,22 @@ title: Incremental Static Regeneration (ISR)
description: Learn how to create or update static pages at runtime with Incremental Static Regeneration.
---

{/* TODO: 번역이 필요합니다. */}

# Incremental Static Regeneration (ISR)

<details>
<summary>Examples</summary>
<summary>예제</summary>

- [Next.js Commerce](https://nextjs.org/commerce)
- [GitHub Reactions Demo](https://reactions-demo.vercel.app/)
- [Static Tweet Demo](https://static-tweet.vercel.app/)

</details>

Next.js allows you to create or update static pages _after_ you’ve built your site. Incremental Static Regeneration (ISR) enables you to use static-generation on a per-page basis, **without needing to rebuild the entire site**. With ISR, you can retain the benefits of static while scaling to millions of pages.
Next.js를 사용하면 사이트를 빌드한 _후_ 정적 페이지를 생성하거나 업데이트할 수 있습니다. Incremental Static Regeneration (ISR)을 사용하면 **전체 사이트를 재빌드할 필요 없이** 페이지별로 정적 생성을 사용할 수 있습니다. ISR을 사용하면 정적 페이지의 장점을 유지하면서 수백만 개의 페이지로 확장할 수 있습니다.

> **Good to know**: The [`edge` runtime](/docs/pages/api-reference/edge) is currently not compatible with ISR, although you can leverage `stale-while-revalidate` by setting the `cache-control` header manually.
> **알아두면 좋은 점**: [`edge` runtime](/docs/pages/api-reference/edge)은 현재 ISR과 호환되지 않지만, `cache-control` 헤더를 수동으로 설정하여 `stale-while-revalidate`를 활용할 수 있습니다.

To use ISR, add the `revalidate` prop to `getStaticProps`:
ISR을 사용하려면, `revalidate` prop을 `getStaticProps`에 추가하세요:

```jsx
function Blog({ posts }) {
Expand All @@ -33,9 +31,9 @@ function Blog({ posts }) {
)
}

// This function gets called at build time on server-side.
// It may be called again, on a serverless function, if
// revalidation is enabled and a new request comes in
// 이 함수는 빌드 시 서버 측에서 호출됩니다.
// 재검증이 활성화되고 새로운 요청이 들어오면,
// 서버리스 함수에서 다시 호출될 수 있습니다.
export async function getStaticProps() {
const res = await fetch('https://.../posts')
const posts = await res.json()
Expand All @@ -44,122 +42,122 @@ export async function getStaticProps() {
props: {
posts,
},
// Next.js will attempt to re-generate the page:
// - When a request comes in
// - At most once every 10 seconds
revalidate: 10, // In seconds
// Next.js는 페이지 재생성을 시도합니다:
// - 요청이 들어올 때
// - 최대 10초마다 한 번씩
revalidate: 10, // 초 단위
}
}

// This function gets called at build time on server-side.
// It may be called again, on a serverless function, if
// the path has not been generated.
// 이 함수는 빌드 시 서버 측에서 호출됩니다.
// 경로가 생성되지 않은 경우,
// 서버리스 함수에서 다시 호출될 수 있습니다.
export async function getStaticPaths() {
const res = await fetch('https://.../posts')
const posts = await res.json()

// Get the paths we want to pre-render based on posts
// 게시물을 기반으로 사전 렌더링할 경로를 가져옵니다.
const paths = posts.map((post) => ({
params: { id: post.id },
}))

// We'll pre-render only these paths at build time.
// { fallback: 'blocking' } will server-render pages
// on-demand if the path doesn't exist.
// 빌드 시 이러한 경로만 사전 렌더링합니다
// 경로가 존재하지 않는 경우, { fallback: 'blocking' }은
// 온디맨드로 페이지를 서버 렌더링합니다.
return { paths, fallback: 'blocking' }
}

export default Blog
```

When a request is made to a page that was pre-rendered at build time, it will initially show the cached page.
빌드 시 사전 렌더링된 페이지에 요청을 하면 처음에는 캐시된 페이지가 표시됩니다.

- Any requests to the page after the initial request and before 10 seconds are also cached and instantaneous.
- After the 10-second window, the next request will still show the cached (stale) page
- Next.js triggers a regeneration of the page in the background.
- Once the page generates successfully, Next.js will invalidate the cache and show the updated page. If the background regeneration fails, the old page would still be unaltered.
- 초기 요청 후 10초 이내에 발생한 페이지에 대한 모든 요청은 캐시되며 즉시 처리됩니다.
- 10초가 지난 후의 다음 요청은 여전히 캐시된 (오래된) 페이지를 표시합니다.
- Next.js는 백그라운드에서 페이지 재생성을 트리거합니다.
- 페이지가 성공적으로 생성되면, Next.js는 캐시를 무효화하고 업데이트된 페이지를 표시합니다. 백그라운드 재생성이 실패하면, 이전 페이지가 그대로 유지됩니다.

When a request is made to a path that hasn’t been generated, Next.js will server-render the page on the first request. Future requests will serve the static file from the cache. ISR on Vercel [persists the cache globally and handles rollbacks](https://vercel.com/docs/concepts/next.js/incremental-static-regeneration?utm_source=next-site&utm_medium=docs&utm_campaign=next-website).
생성되지 않은 경로로 요청이 들어오면, Next.js는 첫 번째 요청에 대해 페이지를 서버 렌더링합니다. 이후의 요청은 캐시에서 정적 파일을 제공합니다. Vercel의 ISR은 [캐시를 전역적으로 유지하고 롤백을 처리합니다](https://vercel.com/docs/concepts/next.js/incremental-static-regeneration?utm_source=next-site&utm_medium=docs&utm_campaign=next-website).

> **Good to know**: Check if your upstream data provider has caching enabled by default. You might need to disable (e.g. `useCdn: false`), otherwise a revalidation won't be able to pull fresh data to update the ISR cache. Caching can occur at a CDN (for an endpoint being requested) when it returns the `Cache-Control` header.
> **알아두면 좋은 점**: 업스트림 데이터 제공자가 기본적으로 캐싱을 활성화했는지 확인하세요. 비활성화해야 할 수도 있습니다(예: `useCdn: false`). 그렇지 않으면 재검증이 ISR 캐시를 업데이트하기 위해 새로운 데이터를 가져올 수 없습니다. 캐싱은 (요청된 엔드포인트에 대해) `Cache-Control` 헤더를 반환할 때 CDN에서 발생할 수 있습니다.

## On-Demand Revalidation

If you set a `revalidate` time of `60`, all visitors will see the same generated version of your site for one minute. The only way to invalidate the cache is from someone visiting that page after the minute has passed.
`revalidate` 시간을 `60`으로 설정하면, 모든 방문자는 1분 동안 동일한 버전의 사이트를 보게 됩니다. 캐시를 무효화하는 유일한 방법은 1분이 지난 후 누군가 해당 페이지를 방문하는 것입니다.

Starting with `v12.2.0`, Next.js supports On-Demand Incremental Static Regeneration to manually purge the Next.js cache for a specific page. This makes it easier to update your site when:
`v12.2.0`부터 Next.js는 특정 페이지에 대한 Next.js 캐시를 수동으로 삭제할 수 있는 온디맨드 Incremental Static Regeneration을 지원합니다. 이를 통해 다음과 같은 경우에 사이트를 더 쉽게 업데이트할 수 있습니다:

- Content from your headless CMS is created or updated
- Ecommerce metadata changes (price, description, category, reviews, etc.)
- 헤드리스 CMS의 콘텐츠가 생성되거나 업데이트된 경우
- 전자상거래 메타데이터 변경 (가격, 설명, 카테고리, 리뷰 등)

Inside `getStaticProps`, you do not need to specify `revalidate` to use on-demand revalidation. If `revalidate` is omitted, Next.js will use the default value of `false` (no revalidation) and only revalidate the page on-demand when `revalidate()` is called.
`getStaticProps` 내부에서 온디맨드 재검증을 사용하기 위해 `revalidate`를 지정할 필요가 없습니다. `revalidate`를 생략하면, Next.js는 기본값인 `false` (재검증 없음)를 사용하고 `revalidate()`가 호출될 때만 온디맨드로 페이지를 재검증합니다.

> **Good to know**: [Middleware](/docs/pages/building-your-application/routing/middleware) won't be executed for On-Demand ISR requests. Instead, call `revalidate()` on the _exact_ path that you want revalidated. For example, if you have `pages/blog/[slug].js` and a rewrite from `/post-1` -> `/blog/post-1`, you would need to call `res.revalidate('/blog/post-1')`.
> **알아두면 좋은 점**: [Middleware](/docs/pages/building-your-application/routing/middleware)는 온디맨드 ISR 요청에 대해 실행되지 않습니다. 대신, 재검증하려는 _정확한_ 경로에서 `revalidate()`를 호출하세요. 예를 들어 `pages/blog/[slug].js`가 있고 `/post-1` -> `/blog/post-1`의 rewrite가 있는 경우, `res.revalidate('/blog/post-1')`를 호출해야 합니다.

### Using On-Demand Revalidation

First, create a secret token only known by your Next.js app. This secret will be used to prevent unauthorized access to the revalidation API Route. You can access the route (either manually or with a webhook) with the following URL structure:
먼저 Next.js 앱에서만 알 수 있는 비밀 토큰을 생성합니다. 이 비밀 토큰은 재검증 API 라우트에 대한 무단 접근을 방지하는 데 사용됩니다. 다음 URL 구조로 (수동으로 또는 웹훅으로) 경로에 접근할 수 있습니다:

```bash filename="Terminal"
https://<your-site.com>/api/revalidate?secret=<token>
```

Next, add the secret as an [Environment Variable](/docs/pages/building-your-application/configuring/environment-variables) to your application. Finally, create the revalidation API Route:
다음으로, 애플리케이션에 비밀 토큰을 [환경 변수](/docs/pages/building-your-application/configuring/environment-variables)로 추가합니다. 마지막으로, 재검증 API 라우트를 생성합니다:

```js filename="pages/api/revalidate.js"
export default async function handler(req, res) {
// Check for secret to confirm this is a valid request
// 이 요청이 유효한지 확인하기 위해 비밀 토큰을 확인합니다.
if (req.query.secret !== process.env.MY_SECRET_TOKEN) {
return res.status(401).json({ message: 'Invalid token' })
}

try {
// this should be the actual path not a rewritten path
// e.g. for "/blog/[slug]" this should be "/blog/post-1"
// 이 경로는 rewritten 경로가 아닌 실제 경로여야 합니다.
// 예: "/blog/[slug]"의 경우 "/blog/post-1"이어야 합니다.
await res.revalidate('/path-to-revalidate')
return res.json({ revalidated: true })
} catch (err) {
// If there was an error, Next.js will continue
// to show the last successfully generated page
// 오류가 발생한 경우
// Next.js는 마지막으로 성공적으로 생성된 페이지를 계속 표시합니다.
return res.status(500).send('Error revalidating')
}
}
```

[View our demo](https://on-demand-isr.vercel.app) to see on-demand revalidation in action and provide feedback.
[데모](https://on-demand-isr.vercel.app)에서 온디맨드 재검증이 동작하는 것을 확인하고 피드백을 제공하세요.

### Testing on-Demand ISR during development

When running locally with `next dev`, `getStaticProps` is invoked on every request. To verify your on-demand ISR configuration is correct, you will need to create a [production build](/docs/pages/api-reference/next-cli#build) and start the [production server](/docs/pages/api-reference/next-cli#production):
`next dev`로 로컬에서 실행할 경우, 모든 요청에 대해 `getStaticProps`가 호출됩니다. 온디맨드 ISR 구성이 올바른지 확인하려면 [프로덕션 빌드](/docs/pages/api-reference/next-cli#build)를 생성하고 [프로덕션 서버](/docs/pages/api-reference/next-cli#production)를 시작해야 합니다:

```bash filename="Terminal"
$ next build
$ next start
```

Then, you can confirm that static pages have successfully revalidated.
그런 다음, 정적 페이지가 성공적으로 재검증되었는지 확인할 수 있습니다.

## Error handling and revalidation

If there is an error inside `getStaticProps` when handling background regeneration, or you manually throw an error, the last successfully generated page will continue to show. On the next subsequent request, Next.js will retry calling `getStaticProps`.
백그라운드 재생성을 처리할 때 `getStaticProps` 내부에 오류가 발생하거나, 수동으로 오류를 발생시키면 마지막으로 성공적으로 생성된 페이지가 계속 표시됩니다. 다음 후속 요청 시, Next.js는 `getStaticProps` 호출을 다시 시도합니다.

```jsx
export async function getStaticProps() {
// If this request throws an uncaught error, Next.js will
// not invalidate the currently shown page and
// retry getStaticProps on the next request.
// 이 요청에서 예기치 않은 오류가 발생하면,
// Next.js는 현재 표시된 페이지를 무효화하지 않고
// 다음 요청 시 getStaticProps를 다시 시도합니다.
const res = await fetch('https://.../posts')
const posts = await res.json()

if (!res.ok) {
// If there is a server error, you might want to
// throw an error instead of returning so that the cache is not updated
// until the next successful request.
// 서버 오류가 발생한 경우,
// 다음 요청이 성공할 때까지 캐시가 업데이트되지 않도록
// 반환하는 대신 오류를 발생시키는 것이 좋습니다.
throw new Error(`Failed to fetch posts, received status ${res.status}`)
}

// If the request was successful, return the posts
// and revalidate every 10 seconds.
// 요청이 성공하면 게시물을 반환하고
// 10초마다 재검증합니다.
return {
props: {
posts,
Expand All @@ -171,16 +169,16 @@ export async function getStaticProps() {

## Self-hosting ISR

Incremental Static Regeneration (ISR) works on [self-hosted Next.js sites](/docs/pages/building-your-application/deploying#self-hosting) out of the box when you use `next start`.
Incremental Static Regeneration (ISR)은 `next start`를 사용할 때 [자체 호스팅된 Next.js 사이트](/docs/pages/building-your-application/deploying#self-hosting)에서 기본적으로 작동합니다.

Learn more about [self-hosting Next.js](/docs/pages/building-your-application/deploying#self-hosting).
[Next.js 자체 호스팅](/docs/pages/building-your-application/deploying#self-hosting)에 대해 자세히 알아보세요.

## Version History

| Version | Changes |
| --------- | --------------------------------------------------------------------------------------- |
| `v14.1.0` | Custom `cacheHandler` is stable. |
| `v12.2.0` | On-Demand ISR is stable |
| `v12.1.0` | On-Demand ISR added (beta). |
| `v12.0.0` | [Bot-aware ISR fallback](https://nextjs.org/blog/next-12#bot-aware-isr-fallback) added. |
| `v9.5.0` | Base Path added. |
| 버전 | 변경 사항 |
| --------- | ------------------------------------------------------------------------------------- |
| `v14.1.0` | 커스텀 `cacheHandler` 안정화 |
| `v12.2.0` | 온디맨드 ISR 안정화 |
| `v12.1.0` | 온디맨드 ISR 추가 (베타) |
| `v12.0.0` | [Bot-aware ISR fallback](https://nextjs.org/blog/next-12#bot-aware-isr-fallback) 추가 |
| `v9.5.0` | Base Path 추가 |
Loading