Incremental Static Regeneration

Static site generation (SSG) turns every page into an HTML file before the site is deployed. Nothing has to be computed when a request arrives, so pages appear fast, and a traffic spike costs almost nothing because the server is only handing over files. The catch is that each file is frozen at the moment it was produced.

Fixing one character therefore meant rebuilding everything. On a site with 5,000 generated documents, correcting a typo in one of them triggers a build that regenerates the other 4,999 as well, and that build takes 20 minutes. Ten corrections in a day cost three hours of waiting.

For the people editing content, the problem always surfaced as the same exchange. "I just fixed the price — when does the site show it?" "Build's running, so about 20 minutes." When something was urgent they'd ask for the deploy to be moved up, and once those requests piled up a few times a day, an engineer's job started to include pressing the build button on request.

Switching to server-side rendering (SSR) makes the freshness problem disappear, but then the server draws the page again on every single request. A page that changes once a day gets redrawn hundreds of times a second, and the server bill grows to match. Incremental Static Regeneration (ISR) splits the difference. Most of the time it hands over a prebuilt file the way static generation does, and only the pages whose time is up get quietly rebuilt in the background.

Write a regeneration interval in seconds next to each page and the framework handles the rest. The part that separates this from static generation is that the unit of work is one page, and it runs independently of deploys.

1. Build the pages at deploy time. This step is identical to static generation. The resulting HTML sits in storage waiting for requests.
2. Attach an expiry to each page. Product detail pages might get 60 seconds, an announcement list 600, depending on how fast the underlying content moves. Smaller numbers mean fresher pages and more rebuilds.
3. Serve the stored file to every request that arrives before the expiry. Inside this window, performance matches plain static generation exactly.
4. On the first request after the expiry, hand that visitor the old file anyway and start building a new one in the background. Nobody waits, at the cost of one person seeing the previous content one more time.
5. Replace the stored file when the rebuild finishes. Requests from that point on get the new content. If the rebuild fails, the old file stays in place, so the page never breaks.

Changes that can't wait for the interval can trigger a rebuild directly. A content tool sends a request naming the path it just saved, and that one page is regenerated regardless of how much of its expiry is left. Corrected prices and wrong copy that went live are the usual reasons to reach for it.

The fit is good when there are many pages, the content changes occasionally, and everyone sees the same thing. Product detail pages, blog posts, help articles, and job listings are the standard examples. Pagedeck's 900 help articles are one of them: a full build takes 14 minutes, while regenerating a single edited article takes 2 seconds.

Pages that differ per person are the opposite case. A cart, a notification inbox, or a dashboard depends on who is logged in, so one stored file can't be handed to everyone. Those screens are drawn with server-side rendering or client-side rendering (CSR), where the browser carries the login session and fetches its own data before drawing.

Values that need to be close to real time don't fit either. Put remaining stock or a live auction bid on a page with a 60-second expiry and visitors can see a number that is a full minute out of date. The usual answer is to mix approaches within one page: keep the bulk of it static and let the browser fetch just the stock number separately.

There are two limits worth knowing up front. The first visitor after an expiry always sees stale content once, by design. And stored pages accumulate per server, so in a setup spread across regions, one region can be serving the new version while another is still on the old one for a few minutes.

"I put this page on ISR with a 60-second expiry."

Freshness is being traded away for up to a minute in exchange for static-file server costs.

"I edited it, why hasn't it changed? Oh, the regeneration hasn't run yet."

The expiry hasn't passed, so the stored file is still going out.

"Prices have to be live, so let's fetch just that part on the client."

A suggestion to peel off the one changing piece rather than move the whole page to server rendering.

Pagedeck's help articles ship this way. The people editing them sit in customer success rather than engineering, so edits arrive several times a day. Sofia used to ask Theo to deploy every time she fixed a sentence, and Theo would kick off the 14-minute build.

Now, when Sofia saves in the content tool, that single article is regenerated. Theo is out of the loop and the wait is down to 2 seconds. A new question came with the change, though. Every so often Sofia says the page looks the same after saving, and nine times out of ten it's a request that landed inside the expiry window and got the stored file. Theo's answer is to reload once more.

The most common misreading is that the rebuild happens the instant content is saved. Databases behave that way, so the expectation carries over. In reality the rebuild starts only when someone visits the page after its expiry has passed. A page nobody opens stays exactly as it was, even a day later. Miss this and you end up reloading a page nobody else visits, wondering why the change refuses to appear.

Assuming that a shorter expiry is always better is the other one. One second feels closer to live, so it's tempting. What it actually produces is a rebuild on nearly every request, which costs about what server-side rendering costs, while visitors still get served the stale version each time. That setting collects the downside of both approaches. Set the interval to match how often the content really changes, and handle the edits that need to be faster by triggering a rebuild directly.