Rendering
Every page renders one of three ways, and each folder of app/ chooses its own.
render | The page is | Good for |
|---|---|---|
"server" | Rendered per request, then hydrated in the browser | Articles, search, anything per user or with SEO |
"static" | Built once at build time, then hydrated | Marketing pages, docs, legal pages |
"client" | Rendered in the browser | Dashboards, editors, apps behind a login |
Setting it
A folder's _config.js sets how its pages, and every folder below it, render:
// app/admin/_config.js
import { defineRoute } from "@opentf/afw";
export default defineRoute({ render: "client" });A site that needs all three, set with four small files:
app/
├─ _config.js { render: "server" } the default for the whole app
├─ page.jsx / server
├─ articles/[slug]/page.jsx /articles/hello server (inherited)
├─ (legal)/
│ ├─ _config.js { render: "static" }
│ ├─ privacy/page.jsx /privacy static
│ └─ terms/page.jsx /terms static
├─ about/
│ ├─ _config.js { render: "static" }
│ └─ page.jsx /about static
└─ admin/
├─ _config.js { render: "client" }
├─ layout.jsx
└─ editor/page.jsx /admin/editor client (inherited)The rules
Nearest wins: a page uses the closest
_config.jsin its folder or above it.One file per folder:
_config.jsor_config.ts. Both in one folder is a build error.Route groups work as folders:
(legal)/_config.jscovers what the group holds without changing its URLs.The app default is the root
app/_config.js. Without one, pages render in the browser (client).renderis a string literal. It decides what each bundle contains (a client page never enters the server bundle), so the build reads it without running the file.render: isAdmin ? "client" : "server"is a build error that says so.Unknown keys are errors, so a typo never falls back to the inherited value silently.
Options
| Key | For | Value |
|---|---|---|
render | every folder | "server", "static" or "client"; inherited when left out |
paths | a dynamic static page ([slug]/page.jsx) | () => [{ slug: "hello" }, …], may be async; the pages to build |
data | client pages | "server" (default): the loader runs on the server and its data comes with the page; "client": the page fetches its own |
pathssits in the_config.jsbeside the dynamic page it lists; anywhere else is an error.pathsis ordinary code: it runs at build time and can query a database.A page's own
getStaticPathsstill works;pathstakes precedence.
Client pages
The server never loads the page module, so it may use browser-only code (an editor library,
window,localStorage) at import time.Layouts above it still render on the server: the site header appears at once, and the page is built into the layout's slot in the browser.
Its loader still runs on the server, under the folder's middleware, and the data comes with the page (unless
data: "client").A client layout makes everything inside it client-rendered too. A
serverorstaticpage inside a client layout is a build error: the server cannot render inside a layout it never loads.
Static pages
Prebuilt at build time to
<path>/index.html, then served as files.The middleware still runs for them:
app/admin/_middleware.jsstill guards a static/adminpage.Loaders run at build time, with no request: a static page's loader cannot read cookies or headers.
Dynamic routes: the pages
pathslists are prebuilt; any other matching URL is rendered when it is requested.In a fully static app, client pages are prebuilt as their layouts around an empty slot.
No sitemap or
robots.txtin an app with a server. Only its static pages are prebuilt, so a generated sitemap would list just those. Put your own inpublic/sitemap.xmlandpublic/robots.txt, or answer them from an API route. A fully static app generates both (with a site URL).
The esdev workflow prebuilds the static pages of a fully static site. In an app with a server (Mixed), its static pages are rendered per request for now; the response and the x-afw-render label are the same.
Loading, error and 404 files
loading.jsxanderror.jsxfollow the policy of the folder they are in.404.jsxis prerendered to404.htmlin a static site, and rendered by the server when the app has one.
Seeing what each page does
The build prints a route table:
TEXTAFW routes Route Render From / server app/_config.js /about static app/about/_config.js /admin/editor client app/admin/_config.tsroutes.jsonbeside the client build (Vite workflow) lists each route, its policy and the file that set it, for tools and deploy adapters.Every rendered page response carries
x-afw-render(server,staticorclient), in development and production.Development works like production: both dev servers render each page by its policy, static pages on request. A fully static esdev site (no server) renders in the browser in development.
The Vite dev server renders pages for browser requests only, those that accept
text/html. A plaincurlgets the client shell; send the header to see the server render:curl -H "accept: text/html" http://localhost:5173/todos.
One browser-only widget
For a single component that needs the browser (a map, a chart) inside a server page, keep the page as it is and make the component lazy: the server sends a placeholder, and the browser loads and renders the component.
Not yet
Revalidation (rebuilding static pages on a schedule or on demand) and cache headers per route. Unknown keys such as
revalidateandcacheare refused until they exist.