Static Export on Three Sites: Next.js, Vite and Prerendering

Three rendering strategies and the one we use

Server-side rendering builds a page on each request. Static generation builds it once, during the build. Static export goes one step further and leaves no application server at all, only files.

The choice depends on how often content changes and whether it differs per visitor. Our sites have no accounts and no per-visitor pages, and their content changes when we deploy. Static export fits that case, so all three sites use it.

Static export in Next.js

bbmmtech.com sets output to export in its Next.js configuration, and the build writes the whole site to a folder named out.

Two more settings follow from that choice. trailingSlash is true, so each route is a folder with an index.html inside and any file host can serve it. images.unoptimized is true, because the image optimizer is a server feature.

A dynamic route has to list its pages in advance. Each of the three dynamic routes exports generateStaticParams.

• The article route returns the slug of every released article.
• The tag route returns every tag used by at least two articles.
• The legal route returns the slug of each legal document.

Six more routes produce files, and each is marked force-static: robots.txt, sitemap.xml, the web manifest, llms.txt, llms-full.txt and the RSS feed. Their code runs once during the build and the result is saved as a file.

What static export removes

A static export runs no code at request time, so four server features need a substitute.

• Redirects. The old /privacy and /terms addresses on bbmmtech.com are small static pages with a meta refresh and a canonical link to the new address.
• Response headers. A _headers file in the public folder is copied into the output and read by the host. It sets five security headers on every path and a one-year immutable cache on the hashed build assets.
• Image resizing. textpack.app uses a custom image loader that maps a product screenshot to a pre-sized WebP file. Each screenshot is stored at five widths from 384 to 1920 pixels.
• The current time. Output that depends on the date is computed when the build runs. Our deploy workflow therefore also runs on a timer twice a day, so that output advances without a push.

The timer was added for a staged release function that compares the build date with a start date. That function is switched off at present and every article is released.

An unknown path is answered by a 404.html file, which the host serves with a 404 status.

Prerendering a Vite and React app

flowoapp.com is a single-page React app built with Vite, and a script turns it into static pages after the bundle is built. The build command runs six steps in order.

1. 1.Collect journal articles delivered as JSON into one module.
2. 2.Snapshot the public help centre into a data file.
3. 3.Run the Vite build.
4. 4.Bundle the worker for the one dynamic endpoint.
5. 5.Prerender every page.
6. 6.Validate the output.

The prerender step first bundles a server entry with Vite. That entry renders the hero, the guide pages, the journal articles and a few utility pages to static markup with the React components the browser uses. The script places each result inside the root element of the built index.html and rewrites the head for that page.

The list of routes written in this step then produces sitemap.xml and llms-full.txt. The validation step fails the build if a listed page lacks a file, a title, an h1 or a single canonical link.

In the browser, React renders over the static markup with createRoot. On the home page it waits until the browser has painted the static hero. On a guide or an article it first loads that page's chunk, so the static page is replaced by the same page and no loading state appears between the two.

Variation per visit without a server

A static page is the same bytes for every visitor, yet parts of the Flowo home page differ per visit. The store buttons and the campaign headline are solved inside the HTML, and language is solved with separate pages.

The prerendered hero contains every variant. It holds the buttons for iOS, for Android and for other platforms, and on the English page it holds every campaign headline. An inline script at the top of the head runs before first paint. It reads the user agent and the campaign parameters, sets attributes on the html element, and adds a style rule that hides the variants that do not apply.

Language is handled on the root address only. When a saved or browser language other than English has its own home page, the script replaces the location with that page before anything renders. The five language home pages are separate prerendered files that link to each other with hreflang.

How the files are deployed

Both bbmmtech.com and flowoapp.com deploy from a GitHub Actions workflow that builds once and uploads the output folder to Cloudflare Pages.

The flowoapp.com workflow runs lint, the unit tests and the build before anything is uploaded. It packs the output with tar so that dot-directories such as .well-known survive. Before the upload it checks that index.html, 404.html, the headers file, the worker and the routes file are all present. A push to main is a production deploy, and a manual run from another branch is a preview.

The bbmmtech.com workflow sends one build artifact to two static hosts, Cloudflare Pages and GitHub Pages. With both current, a DNS change in either direction is a complete rollback. After a successful deploy, a job submits the sitemap URLs to IndexNow.

Caching follows from the file names. On flowoapp.com, HTML keeps the host default and is revalidated on every request, so a deploy is visible at once. Content-hashed assets are cached for one year as immutable. Media files that keep their names across re-encodes are fresh for one day and may be served stale for a week while they revalidate.

textpack.app is a Next.js export as well. Its CI builds the out folder on every push to main, and its host configuration serves that folder with clean URLs.

When we would add a server

We have built no server-rendered page on any of the three sites. We would add one for content that changes between deploys or for pages that differ per signed-in visitor, and neither exists on these sites today.