Static Site Generation

Who draws the screen changes what it costs. Client-side rendering sends an empty HTML shell first, then the browser downloads and runs JavaScript before any content appears. Drawing in the browser keeps the server light, but the user watches a blank screen for a few seconds and a search bot collects a document with nothing in it.

Server-side rendering has the server assemble finished HTML on every request. The first screen is fast and bots see the content. In exchange, every single request means a database query and a document assembled from scratch.

Pagedeck's help documentation is where the waste in that became visible. There were 400 documents, and one or two got edited in a given week. Traffic ran at 30,000 visits a day, so the server was reassembling the same documents 30,000 times. Of those 30,000, the number where the content had actually changed was in the single digits.

So the timing moved. If the result is going to be identical anyway, build it once at deploy time rather than at request time. Static site generation is that single build, pushed into the build step. Nothing about the page changes; only the moment the work happens does.

At build time an HTML file gets written for each page, and a request is answered with the file as-is. Five steps.

1. Determine the list of addresses to build. Either derived automatically from the file structure, or returned by a function you write. Four hundred help documents produce 400 addresses here.
2. Fetch the data each address needs. Database queries and calls to external services happen at this point. Because the step finishes during the build, no query runs at the moment of an actual request.
3. Render each page and write it to a file. The output is finished HTML, often accompanied by a separate JSON file holding data the page will want later.
4. Upload the output to a CDN. A CDN is the distribution network that serves files from a point close to the user. Static files mean deployment finishes without a server behind it.
5. The browser paints the HTML first, then JavaScript attaches and the buttons and inputs become operable. That attaching step is called hydration.

One constraint falls out of this, and it is the constraint that decides whether the approach suits a given page at all. Changing content means rebuilding. Fixing a single typo rebuilds the whole set, and that time scales roughly with page count: one minute at 400 pages, past 40 minutes at 50,000.

Long builds make deploying frightening. With 40 minutes to wait on any fix, changes get batched up and released together, and then working out which change broke something becomes hard. Incremental static regeneration is the approach aimed at exactly that.

The targets are pages that look the same to everyone and don't change often.

1. Documentation and help centers. Content doesn't vary per user, and a high share of arrivals come from search.
2. Marketing pages and blogs. First-screen speed is the bounce rate, and search accounts for more than half the traffic.
3. Glossaries and other list-shaped reference material. Many pages, each independent of the others, which is the shape that benefits most per unit of build time.
4. Product overview and pricing. Changes about once a quarter, so a rebuild per change costs nothing in practice.

The reason technical SEO work favors this is straightforward. Technical SEO is the engineering that makes a site readable to search engines. The document a bot receives already contains the content, so nothing waits on JavaScript execution and crawl capacity goes further.

Where it doesn't fit is anywhere the screen differs per user: a logged-in dashboard, values like stock levels or prices that move by the minute, or search results where the combinations of conditions are unbounded. Either there is nothing to build ahead of time, or what you built starts going stale immediately. A dashboard built at deploy time would show every user the same numbers, which is worse than slow.

In practice one product mixes approaches page by page. Documentation gets built statically, dashboards render per request, and stretches that swap content within one screen the way a single page application does are left to the browser.

"Let's move help onto static generation. There's no reason to render 30,000 requests a day."

Stop reassembling pages whose content is identical.

"Forty minutes of build to fix one typo. We need a different approach here."

Page count has pushed the rebuild cost past what's tolerable.

"We made the pricing page static and now the exchange rate isn't updating."

The value baked in at build time has gone stale.

Pagedeck builds help, the blog, and the template gallery statically. The first move Theo made was the 400 help documents, and server response time dropped from 240 milliseconds to 20. Handing over a file leaves the server with essentially nothing to do, and the database stopped seeing traffic from those pages entirely.

The problem arrived after the gallery grew to 8,000 pages. Builds reached 14 minutes, which made urgent fixes uncomfortable. Ravi had to wait 14 minutes to correct one line of copy, and since he batched other changes in while waiting, working out what had broken what got harder. So the gallery moved to being rebuilt only when needed.

The word static makes people read this as ruling out dynamic behavior. Pre-writing HTML files does sound like a page that doesn't move. But what gets pre-written is only the first screen's HTML; once JavaScript attaches, search boxes, maps, and carts all work as normal. Showing login state or accepting comments on a static page is fine too — those parts just get fetched after the screen appears. The distinction is between what is known at build time and what is not, rather than between still and moving.

Treating it as always the fastest option is also frequent. There's no work left at request time, so it looks that way. The claim holds within a range, though: page counts that stay manageable and content that doesn't change often. Past tens of thousands of pages you pay in lengthened deploy cycles, and on pages whose values move, users end up reading something out of date. It isn't a question of picking the fast option but of deciding, per page, what to give up — freshness, deploy speed, or server cost.