In a meta-framework, what is a static export, and what must a file host do to serve it?

## What the build actually produces A meta-framework normally emits two halves: a set of assets the browser downloads, and a **server entry** that can render a route while a request is in flight. A **static export** is the build mode that drops the second half. The renderer runs at build time across the routes the project can enumerate, and each result is serialised to an HTML document on disk. Around those documents sit the content-hashed JavaScript and CSS chunks, fonts, images, and any files copied verbatim from a public directory. The output directory *is* the deployable artifact. Nothing inside it is a program the host is expected to start, keep alive, or invoke. That single fact is the whole of the difference: - a **server-backed deployment** hands the host a process (or a per-request function) and asks it to run your code on every request; - a **static export** hands the host a folder and asks it to return bytes. ## What the host has to provide A files-only target is defined by a short contract. To serve an exported artifact, a host needs to: 1. **Resolve a URL path to a stored file**, including a convention for a path that names a directory rather than a file. 2. **Answer with a plausible `Content-Type`** per extension, so documents parse as HTML and scripts as JavaScript. 3. **Have an answer for a path that matches nothing** - ideally a document of your choosing, returned with a real status rather than a success status. 4. **Let you set response headers**, at minimum `Cache-Control`, because immutable hashed assets and HTML documents want opposite policies. Optional, and where hosts differ most: redirect and rewrite rules, and sometimes a small amount of request-time logic. Those are *host* features that you configure; the app no longer brings any request-time logic of its own. ## What survives and what does not | | Server-backed deployment | Files-only static export | |---|---|---| | Who renders the first HTML | the server, per request | the build, once per route | | When the page's data is read | while the request is open | while the build runs | | A URL nothing matches | reaches the app's handler | reaches the host's fallback | | A form write | a server handler in the app | must go to another origin | | Publishing changed content | the next read picks it up | the next build replaces files | | What runs after the document loads | the client bundle | the client bundle | The last row is the one candidates most often get wrong. **"Static" describes the origin, not the page.** The exported documents are hydrated by the same JavaScript bundle a server-backed build would have shipped: event handlers attach, client-side navigation takes over, and the app can call any API it is allowed to reach. A files-only site can be a genuinely rich application. What it cannot do is make a decision *before* it answers a request. ## Secrets and the artifact boundary Because the artifact is downloadable in full, **every value the build inlined into a document or a chunk is public** - including values that came from a build-time environment variable and never appeared in source control. Anyone can fetch the chunk and read it. A credential that must stay private has to live behind a service the browser calls without ever holding it; the exported app can only carry values you would be comfortable printing on the page. The same boundary applies to data. Content that only some readers may see cannot be prerendered into a document that the host will hand to anyone who asks for the URL. Either the document carries no such content and the browser fetches it after load against an API that checks the caller, or the surface does not belong on a files-only target. ## Where this shape fits The natural fits are surfaces whose HTML is the same for everyone at the moment it is built: documentation, marketing pages, changelogs, reference material, and app shells whose data is per-user and fetched after load. The operational upside is real and often undersold - there is no runtime to keep alive, no process to patch, no cold start, and the artifact is trivially copied close to readers. ## The honest caveat Meta-frameworks differ in how much of themselves survives the export. Some refuse to build when a route uses a request-dependent feature; others export what they can and degrade the rest quietly. Some emit one document per route; others emit a single shell document and leave all routing to the client, which changes what the host has to be configured to do. Read what your build actually emitted rather than trusting the mode's name.