# Incremental Static Generation Course: [React](https://www.devtutorials.ai/learn/react) · Section: Render Modes Source: https://www.devtutorials.ai/learn/react/rendering/incremental-static-generation > How ISG works: static generation with revalidation, stale-while-revalidate, background regeneration, on-demand revalidation, caching and consistency, ISG pros and cons, and a News Portal capstone to download. ## Introduction to Incremental Static Generation **Incremental static generation (ISG)** is static generation that updates itself. Pages are made into HTML like in SSG, and visitors get the saved file fast. But each page also has a **revalidate time**, for example 60 seconds. After that time, the server makes a fresh copy **in the background**, one page at a time. "Incremental" means pages are updated one by one, when needed, not by rebuilding the whole site. In Next.js this is called **Incremental Static Regeneration (ISR)**. It is the same idea.
ISG sits between SSG and SSR: pages are static, but they are regenerated after a set time SSG built once; changes need a full rebuild ISG built once; each page refreshes itself after N seconds SSR rendered again for every request
ISG keeps the speed of static pages and adds fresh content.
### Real-World Example A bookshop's "New arrivals" page lists books that change a few times a day. The server saves the rendered HTML page and sends the saved copy to every visitor. After 60 seconds, the next visit still gets the saved copy, but the server builds a new page in the background. The visit after that gets the new list. ## Benefits of ISG - **Fast like static pages.** Most visitors get a saved file. - **Fresh content without full rebuilds.** Changed pages update themselves. - **Scales to many pages.** You do not need to build 100,000 pages up front. Rare pages are made on their first visit. - **Low server work.** A page is rendered at most once per revalidate time, not once per visitor. ## ISG Architecture ### Static Generation with Revalidation Each page is a cache entry: its **HTML**, **when it was generated**, and a **revalidate** time in seconds. In Next.js you write `export const revalidate = 60;` in a page file. The page is then treated as static for 60 seconds at a time. ### Incremental Page Updates When a request comes in after the time is up, only **that** page is regenerated. Other pages stay as they are. A site with 10,000 articles never needs a full rebuild to update one article. ### Content Refresh Workflow ISG uses a pattern called **stale-while-revalidate**: 1. A visitor asks for a page whose time is up (it is **stale**). 2. The server sends the **old** page at once, so the visitor does not wait. 3. In the background, the server fetches the data and renders a **new** page. 4. The new page replaces the old one in the cache. The **next** visitor gets it.
Stale-while-revalidate: the visitor gets the saved page at once, and the server makes a fresh copy in the background Visitor GET /news Cache page v1 (old) Visitor gets v1 now Regenerate in background Cache now has v2 next visitor gets it
Nobody waits for the regeneration. The next visitor sees the new page.
Try it in the simulator. The page has a revalidate time of 10 seconds. Change the article in the "editor", then send requests and watch the cache. The clock runs 1 second per second, and **Skip 5 s** moves it forward.

Clock: {now}s · Database: article v{source} · Cache: page v{cache.version}

{regenUntil !== null ? "regenerating..." : stale ? "STALE (" + age + "s old)" : "FRESH (" + age + "s of " + REVALIDATE + "s)"}

{" "} {" "}

); } `, "main.tsx": `import { createRoot } from "react-dom/client"; createRoot(document.getElementById("root")!).render(); `, }} /> Notice: after the editor changes the article, the first stale request still gets the **old** version. Only the request after the regeneration gets the new one. This short delay is the price of never making visitors wait. Easy Way to Remember: serve the old page now, bake a fresh one for the next visitor. ## ISG Rendering Fundamentals ### Build-Time Rendering At build time, ISG works like SSG: it renders the pages you list. Usually these are the **most popular** ones, such as the home page and the latest articles. You do not have to list every page. ### Background Regeneration After deployment, pages are regenerated **while the site runs**, in the background, on the server. The server fetches fresh data and renders the page again, exactly like a build, but for one page. Pages that were **not** built (an old article, a new one) are made on their **first visit**. That first visitor waits once, like SSR. After that, the page is cached like any other. ### Serving Updated Pages Once a new version is in the cache, every visitor gets it, until it becomes stale again. The cache entry has a **version** number, so you can see when a page changed. The lab uses the real ISG cache from the capstone (`isg.ts`). It builds the home page and article 1. Watch the console as you request pages: MISS (made on first visit), HIT (fresh) and STALE (old page served, refresh started).

{built ? "Build done: / and /articles/1 are in the cache." : "Building..."}

{["/", "/articles/1", "/articles/3"].map((p) => ( ))}

{result}

Tip: wait 5 seconds, then request a page again to see STALE.

); } `, "isg.ts": `// A tiny ISG cache: serve saved HTML, and regenerate it in the background // when it is older than "revalidate" milliseconds (stale-while-revalidate). html: string; generatedAt: number; version: number; } const cache = new Map(); const regenerating = new Set(); async function regenerate(path: string) { const html = await render(path); const old = cache.get(path); cache.set(path, { html, generatedAt: Date.now(), version: (old?.version ?? 0) + 1 }); console.log("[ISG] generated " + path + " (v" + cache.get(path)!.version + ")"); } async function request(path: string): Promise<{ entry: CacheEntry; status: CacheStatus }> { const entry = cache.get(path); if (!entry) { // Not built yet: generate it now, then keep it (on-demand generation) await regenerate(path); return { entry: cache.get(path)!, status: "MISS" }; } if (Date.now() - entry.generatedAt < revalidateMs) return { entry, status: "HIT" }; // Too old: serve the old page now, and refresh it in the background if (!regenerating.has(path)) { regenerating.add(path); regenerate(path).finally(() => regenerating.delete(path)); } return { entry, status: "STALE" }; } return { request, // build time: generate a list of pages before any visitor comes build: async (paths: string[]) => { for (const p of paths) await regenerate(p); }, // on-demand revalidation: refresh one page now (for example after an edit) revalidate: regenerate, }; } `, "render.tsx": `import { renderToStaticMarkup } from "react-dom/server"; // Fetch the data for a path and render it to HTML (what the server does) const match = /^\\/articles\\/(\\d+)$/.exec(path); if (match) { const response = await fetch(API + "/" + match[1] + "?delay=300"); if (!response.ok) return "

Article not found.

"; const article: Article = await response.json(); return renderToStaticMarkup(); } const response = await fetch(API + "?delay=300"); const articles: Article[] = await response.json(); return renderToStaticMarkup(); } `, "pages.tsx": `import type { Article } from "./types"; return (

Top stories

{articles.map((a) => ( ))}
); } return ( ); } `, "types.ts": `export interface Article { id: number; title: string; category: string; summary: string; body: string; } `, "main.tsx": `import { createRoot } from "react-dom/client"; createRoot(document.getElementById("root")!).render(); `, }} /> A HIT takes about 0 ms. A MISS takes as long as fetching and rendering, about 300 ms here. That gap is why ISG builds the popular pages first. ## Content Revalidation ### Revalidation Process **Revalidation** means checking if a cached page is still good, and making a new one if not. For each request, the server asks: - Is the page in the cache? If **no** → generate it now (MISS). - Is it younger than the revalidate time? If **yes** → send it (HIT). - Otherwise → send it, and regenerate in the background (STALE).
The update lifecycle of one page: fresh, stale, regenerating, fresh again Fresh served from cache Stale time is up Regenerate in background Fresh again new version the loop repeats for as long as the site runs
Each page has its own clock.
### Data Refresh Strategies There are three common ways to refresh content: - **Time-based revalidation.** The page refreshes after N seconds. It is simple, but changes appear a little late. - **On-demand revalidation.** Your app tells the server "refresh this page now", usually right after an editor saves. In Next.js this is `revalidatePath("/articles/2")`. Changes appear at once. - **Generate on first visit.** Pages that were never built are made the first time someone asks for them.
Data refresh strategies: time-based, on-demand, and on-demand generation of new pages Time-based revalidate: 60 On-demand revalidate(path) On first visit generate new pages refresh after N seconds refresh right after an edit pages not built yet simple, a little late instant, needs a hook first visitor waits once
Real sites usually combine all three.
### Managing Frequently Updated Content Pick the revalidate time for each **kind** of page:
| Page | Changes | Good revalidate time | |---|---|---| | Breaking news, live scores | Every few seconds | Short (10–30 s), or use SSR instead | | Home page, article lists | Many times a day | 30–60 s, plus on-demand | | Single articles | Rarely after publishing | 1 hour or more, plus on-demand on edit | | About, contact pages | Almost never | 1 day, or plain SSG |
The lab compares time-based and on-demand refresh. Change the title and publish. With on-demand off, the page updates only after the time is up. With it on, the page is regenerated right after publishing. setTitle(e.target.value)} style={{ width: "100%" }} /> {" "}

{info}

); } `, "isg.ts": `// A tiny ISG cache: serve saved HTML, and regenerate it in the background // when it is older than "revalidate" milliseconds (stale-while-revalidate). html: string; generatedAt: number; version: number; } const cache = new Map(); const regenerating = new Set(); async function regenerate(path: string) { const html = await render(path); const old = cache.get(path); cache.set(path, { html, generatedAt: Date.now(), version: (old?.version ?? 0) + 1 }); console.log("[ISG] generated " + path + " (v" + cache.get(path)!.version + ")"); } async function request(path: string): Promise<{ entry: CacheEntry; status: CacheStatus }> { const entry = cache.get(path); if (!entry) { // Not built yet: generate it now, then keep it (on-demand generation) await regenerate(path); return { entry: cache.get(path)!, status: "MISS" }; } if (Date.now() - entry.generatedAt < revalidateMs) return { entry, status: "HIT" }; // Too old: serve the old page now, and refresh it in the background if (!regenerating.has(path)) { regenerating.add(path); regenerate(path).finally(() => regenerating.delete(path)); } return { entry, status: "STALE" }; } return { request, // build time: generate a list of pages before any visitor comes build: async (paths: string[]) => { for (const p of paths) await regenerate(p); }, // on-demand revalidation: refresh one page now (for example after an edit) revalidate: regenerate, }; } `, "render.tsx": `import { renderToStaticMarkup } from "react-dom/server"; // Fetch the data for a path and render it to HTML (what the server does) const match = /^\\/articles\\/(\\d+)$/.exec(path); if (match) { const response = await fetch(API + "/" + match[1] + "?delay=300"); if (!response.ok) return "

Article not found.

"; const article: Article = await response.json(); return renderToStaticMarkup(); } const response = await fetch(API + "?delay=300"); const articles: Article[] = await response.json(); return renderToStaticMarkup(); } `, "pages.tsx": `import type { Article } from "./types"; return (

Top stories

{articles.map((a) => ( ))}
); } return ( ); } `, "types.ts": `export interface Article { id: number; title: string; category: string; summary: string; body: string; } `, "main.tsx": `import { createRoot } from "react-dom/client"; createRoot(document.getElementById("root")!).render(); `, }} /> ## Caching and Updates ### Cache Behavior The ISG cache lives on the server (and often on a CDN in front of it). Each path has **its own** entry and its own clock. A visitor never sees "half" a page: they get either the old version or the new one. ### Content Consistency Because pages refresh one by one, two pages can show **different versions** of the same data for a short time. For example, the article page shows the new title, but the home page list still shows the old one. To keep related pages consistent, revalidate them **together**. After editing article 2, refresh both `/articles/2` and `/` (which lists it). ISG content can be up to one revalidate period old. That is fine for news and shops, but not for things that must always be exact, like a bank balance or stock in a cart. Use SSR or client-side fetching for those. ### Update Lifecycle Putting it together, a page goes through this loop: 1. **Built** at deploy time (or on the first visit). 2. **Fresh:** served from the cache, very fast. 3. **Stale:** the time is up. Still served, but a refresh starts. 4. **Regenerated:** the new version replaces the old one. 5. Back to **fresh**. An on-demand revalidation can jump straight to step 4 at any time. ## Advantages and Limitations of ISG
| Advantages | Limitations | |---|---| | Static speed for most visitors | Content can be up to one revalidate period old | | Fresh content without full rebuilds | Needs a server or a platform that supports it (not plain static hosting) | | Builds stay fast: rare pages are made on first visit | Related pages can briefly disagree | | Server renders each page at most once per period | Harder to debug: "which version am I seeing?" | | Edits can show at once with on-demand revalidation | First visit to an unbuilt page is slower |
| | SSG | ISG | SSR | |---|---|---|---| | When HTML is made | Build time | Build time + background refresh | Every request | | Speed | Fastest | Fast (cached) | Slower | | Freshness | Until the next build | Within the revalidate time | Always fresh | | Hosting | Static files | Server or ISG platform | Server |
## Capstone Project: News Portal You will build **The Book Corner Times**, a small news portal. Articles come from the pretend API at `https://api.bookcorner.dev/articles`. Pages are generated statically, cached with ISG, and refreshed when the newsroom edits a story.
News Portal: listing page and article pages, each with its own cache entry and revalidate time / top stories /articles/1 built /articles/3 on first visit ISG cache: each path keeps its HTML, its age and its version
The newsroom edits data. The cache turns it into pages.
### Create article listing pages `NewsList` (in `pages.tsx`) shows each article's title as a link, its category and a short summary. ### Create article details pages `ArticlePage` shows one article with its category, title and full text, and a link back to the list. ### Generate pages statically `render.tsx` has `renderPage(path)`: it fetches the data for the path and turns the page into HTML with `renderToStaticMarkup`. At "build time", the app calls `isg.build(["/", "/articles/1", "/articles/2"])`. Article 3 is not built; it is made on its first visit. In the lab, click a story on the left to render its page on the right.
/ (listing)
Building...

" }} />
{path}
Building...

" }} />
); } `, "render.tsx": `import { renderToStaticMarkup } from "react-dom/server"; // Fetch the data for a path and render it to HTML (what the server does) const match = /^\\/articles\\/(\\d+)$/.exec(path); if (match) { const response = await fetch(API + "/" + match[1] + "?delay=300"); if (!response.ok) return "

Article not found.

"; const article: Article = await response.json(); return renderToStaticMarkup(); } const response = await fetch(API + "?delay=300"); const articles: Article[] = await response.json(); return renderToStaticMarkup(); } `, "pages.tsx": `import type { Article } from "./types"; return (

Top stories

{articles.map((a) => ( ))}
); } return ( ); } `, "types.ts": `export interface Article { id: number; title: string; category: string; summary: string; body: string; } `, "styles.css": `.portal { font-family: Georgia, serif; display: flex; gap: 12px; flex-wrap: wrap; } .reader { flex: 2; min-width: 260px; border: 2px solid #222; border-radius: 8px; padding: 8px 12px; } .newsroom { flex: 1; min-width: 200px; background: #fff8e6; border-radius: 8px; padding: 8px 12px; font-family: sans-serif; font-size: 13px; } .masthead { font-size: 20px; font-weight: bold; border-bottom: 3px double #222; margin-bottom: 6px; } .bar { font-family: monospace; font-size: 12px; display: flex; gap: 8px; align-items: center; flex-wrap: wrap; } .badge { padding: 1px 6px; border-radius: 4px; color: white; } .badge.HIT { background: #1e7b34; } .badge.STALE { background: #e07b00; } .badge.MISS { background: #2b59c3; } .item { border-bottom: 1px solid #ddd; padding: 4px 0; } .item a { font-weight: bold; color: #111; } .cat { font-family: sans-serif; font-size: 11px; text-transform: uppercase; color: #b42318; margin-left: 6px; } .updated { background: #e3f6e8; color: #1e7b34; padding: 2px 6px; border-radius: 4px; font-family: sans-serif; font-size: 12px; } .newsroom input { width: 100%; padding: 4px; margin: 4px 0; } `, "main.tsx": `import { createRoot } from "react-dom/client"; createRoot(document.getElementById("root")!).render(); `, }} /> ### Implement content revalidation `isg.ts` is the cache. `request(path)` returns the page and a status: MISS, HIT or STALE. The portal uses a revalidate time of 8 seconds, so you can see it work quickly. A real site would use minutes. ### Manage frequently updated articles The **Newsroom** panel edits article 2 through the API (a `PUT` request). With **Revalidate now** ticked, it also calls `isg.revalidate()` for both `/articles/2` and `/`, so the article and the list stay consistent. Without it, the change shows up after the next stale request. ### Display refreshed content automatically The reader view asks the server for the current page every 3 seconds, like a news site that checks for updates. When the version number goes up, it shows **Updated just now**. The bar shows the cache status, the version and the page's age. Here is the finished portal. Open article 2, change its title in the Newsroom, and publish, with and without on-demand revalidation.
The Book Corner Times
{path} {page.status} v{page.version} · {age}s old · revalidate {REVALIDATE_SECONDS}s {updated && Updated just now}
📝 Newsroom

Edit article 2 and publish. Readers get the new page after it is regenerated.

setTitle(e.target.value)} />
); } `, "isg.ts": `// A tiny ISG cache: serve saved HTML, and regenerate it in the background // when it is older than "revalidate" milliseconds (stale-while-revalidate). html: string; generatedAt: number; version: number; } const cache = new Map(); const regenerating = new Set(); async function regenerate(path: string) { const html = await render(path); const old = cache.get(path); cache.set(path, { html, generatedAt: Date.now(), version: (old?.version ?? 0) + 1 }); console.log("[ISG] generated " + path + " (v" + cache.get(path)!.version + ")"); } async function request(path: string): Promise<{ entry: CacheEntry; status: CacheStatus }> { const entry = cache.get(path); if (!entry) { // Not built yet: generate it now, then keep it (on-demand generation) await regenerate(path); return { entry: cache.get(path)!, status: "MISS" }; } if (Date.now() - entry.generatedAt < revalidateMs) return { entry, status: "HIT" }; // Too old: serve the old page now, and refresh it in the background if (!regenerating.has(path)) { regenerating.add(path); regenerate(path).finally(() => regenerating.delete(path)); } return { entry, status: "STALE" }; } return { request, // build time: generate a list of pages before any visitor comes build: async (paths: string[]) => { for (const p of paths) await regenerate(p); }, // on-demand revalidation: refresh one page now (for example after an edit) revalidate: regenerate, }; } `, "render.tsx": `import { renderToStaticMarkup } from "react-dom/server"; // Fetch the data for a path and render it to HTML (what the server does) const match = /^\\/articles\\/(\\d+)$/.exec(path); if (match) { const response = await fetch(API + "/" + match[1] + "?delay=300"); if (!response.ok) return "

Article not found.

"; const article: Article = await response.json(); return renderToStaticMarkup(); } const response = await fetch(API + "?delay=300"); const articles: Article[] = await response.json(); return renderToStaticMarkup(); } `, "pages.tsx": `import type { Article } from "./types"; return (

Top stories

{articles.map((a) => ( ))}
); } return ( ); } `, "types.ts": `export interface Article { id: number; title: string; category: string; summary: string; body: string; } `, "styles.css": `.portal { font-family: Georgia, serif; display: flex; gap: 12px; flex-wrap: wrap; } .reader { flex: 2; min-width: 260px; border: 2px solid #222; border-radius: 8px; padding: 8px 12px; } .newsroom { flex: 1; min-width: 200px; background: #fff8e6; border-radius: 8px; padding: 8px 12px; font-family: sans-serif; font-size: 13px; } .masthead { font-size: 20px; font-weight: bold; border-bottom: 3px double #222; margin-bottom: 6px; } .bar { font-family: monospace; font-size: 12px; display: flex; gap: 8px; align-items: center; flex-wrap: wrap; } .badge { padding: 1px 6px; border-radius: 4px; color: white; } .badge.HIT { background: #1e7b34; } .badge.STALE { background: #e07b00; } .badge.MISS { background: #2b59c3; } .item { border-bottom: 1px solid #ddd; padding: 4px 0; } .item a { font-weight: bold; color: #111; } .cat { font-family: sans-serif; font-size: 11px; text-transform: uppercase; color: #b42318; margin-left: 6px; } .updated { background: #e3f6e8; color: #1e7b34; padding: 2px 6px; border-radius: 4px; font-family: sans-serif; font-size: 12px; } .newsroom input { width: 100%; padding: 4px; margin: 4px 0; } `, "main.tsx": `import { createRoot } from "react-dom/client"; createRoot(document.getElementById("root")!).render(); `, }} /> ## Download Project Files ### Download ISG Project Source Code The complete News Portal is ready as a real ISG project with **Vite**, **React**, **TypeScript**, **React Router** and a small **Express** server. The server keeps an ISG cache: pages are generated at start-up ("build"), served from the cache, regenerated in the background after their revalidate time, and refreshed at once when you publish in the Newsroom. Download ISG Project: [Download News Portal Project](/downloads/react/isg-news-portal.zip) ``` news-portal/ package.json scripts and dependencies server.js Express: ISG cache, revalidation, JSON API isg.config.js revalidate times per route data/articles.json the articles (the "database") index.html template with and src/ entry-server.tsx render(url): load data + renderToString entry-client.tsx hydrateRoot with the page data App.tsx routes routes.ts route matching and loadPageData() server/articlesStore.ts read and write data/articles.json pages/ NewsListPage, ArticlePage, NewsroomPage, NotFoundPage components/ Masthead, ArticleCard, CacheInfo hooks/useAutoRefresh.ts check for a newer version and update the page types/news.ts ``` ### Project Setup Instructions 1. Install **Node.js** 18 or newer from nodejs.org, if you do not have it. 2. Download the ZIP with the link above, and unzip it. You get a folder called `news-portal`. 3. Open a terminal in that folder (in VS Code: File, Open Folder, then Terminal, New Terminal). 4. Install the packages and start the server: ```bash npm install npm run dev ``` Open `http://localhost:5173`. Open the **Newsroom** page in a second tab, edit a story, and watch the first tab update. The terminal logs every HIT, STALE and regeneration. For production, run `npm run build` and then `npm run start`. In the browser's developer tools (F12), open the Network tab and click the page request. The response header `X-ISG-Cache` shows HIT, STALE or MISS, and `X-ISG-Age` shows how old the page is. ## Common mistakes
| Mistake | What you see | Fix | |---|---|---| | Expecting the first request after an edit to show the new content | The visitor still sees the old page | That is stale-while-revalidate; the next request gets the new page, or use on-demand revalidation | | A very short revalidate time on every page | The server renders almost as often as SSR | Use short times only for pages that change often | | Revalidating only the edited article | The home page list shows the old title | Revalidate every page that shows the changed data | | Building every page at deploy time | Very slow builds on big sites | Build popular pages; make the rest on first visit | | Using ISG for per-user or exact data | Users see someone else's or old data | Use SSR or client fetching for carts, balances, dashboards | | Hosting an ISG site as plain static files | Pages never refresh | ISG needs a server or a platform that supports it |
## Check Yourself ## Exercises ## What to Remember - ISG is static generation plus revalidation: pages are cached HTML, and each one is regenerated after its revalidate time. - Stale-while-revalidate: a stale page is still served at once, and the fresh copy goes to the next visitor. Pages not built yet are made on their first visit. - Use time-based revalidation for regular refresh, and on-demand revalidation right after edits. Revalidate related pages together. ISG needs a server or an ISG-ready platform. Next: API Integration