---
title: Flow static generation
description: "Use renderToStatic() to write complete HTML pages and separate fragment files at build time, with predictable URLs and on-demand regeneration."
---

# Static generation

Build HTML files at compile time. `renderToStatic` gives you a context to
render all your pages, then emit fragment files if any page uses `<Defer>` with
a lazy factory. The browser fetches fragments after the shell page loads: no
streaming connection required.

## When to use static generation

Static generation is the right choice when:

- Your content is known at build time (docs, blogs, marketing sites)
- You deploy to a CDN or static file server (S3, Nginx, Cloudflare Pages)
- You want zero server infrastructure for serving pages
- Fragments can be fetched lazily by the client

If you need fragments to arrive in the same HTTP response as the shell, use
[Streaming](/integration/flow/streaming) instead.

## Pure static

No lazy `<Defer>` in your pages? Call `renderToStatic` without an adapter.
Each `ctx.renderPage` call applies any configured shell transforms and returns
a complete HTML document, ready to write to a file.

```tsx
import type { JSX } from "@vincle/core";

import { renderToStatic } from "@vincle/flow";
import { writeFile } from "node:fs/promises";

declare const pages: { Component: () => JSX.Element; out: string }[];

await renderToStatic(async (ctx) => {
  await Promise.all(
    pages.map(async (page) => {
      const html = await ctx.renderPage(() => <page.Component />);
      await writeFile(page.out, "<!DOCTYPE html>\n" + html);
    }),
  );
});
```

## With deferred fragments

Pass an adapter and call `ctx.emitFragments` after rendering each page. Each
deferred fragment is rendered, already `Frame`-wrapped, and passed to your
callback with its id, its URL and its HTML.

```tsx
import type { JSX } from "@vincle/core";

import { renderToStatic } from "@vincle/flow";
import { NativeAdapter } from "@vincle/flow/adapters";
import { writeFile } from "node:fs/promises";

declare const pages: { Component: () => JSX.Element; out: string }[];

await renderToStatic(
  async (ctx) => {
    for (const page of pages) {
      const html = await ctx.renderPage(() => <page.Component />);
      await writeFile(page.out, "<!DOCTYPE html>\n" + html);
      await ctx.emitFragments((_id, url, html) => writeFile("./dist" + url, html));
    }
  },
  { adapter: NativeAdapter },
);
```

The browser loads the shell page first; each `<Defer>` placeholder carries its
fragment's URL, and the adapter fetches it. Fragment files are static HTML at
predictable URLs, so they can be cached aggressively.

The `generatePath` option sets each fragment's URL:

| Option         | Default                              | Description                |
| -------------- | ------------------------------------ | -------------------------- |
| `generatePath` | ``(id) => `/fragments/${id}.html` `` | URL path for each fragment |

`emitFragments` drains the pending fragment registry, so a shared layout can
reuse a target on the next page. Rendering multiple pages before draining
requires targets unique across those pages, otherwise
`ERR_VINCLE_FLOW_DUP_FRAGMENT` is thrown. With the default URL convention,
reused targets write the same file: reuse them only for identical content.
For page-specific content, use globally unique targets or a separate
`renderToStatic` call per page with a page-specific `generatePath`.

## On-demand regeneration

A full rebuild is wasteful when only one piece of data changed: a price, a
stock count, a comment count. Because each fragment is a standalone file at a
predictable URL, only that file needs to change; the shell page that
references it is untouched.

`renderFragment` produces exactly the bytes a full build would have written
for one `id`, without rendering any page:

```tsx
import { renderFragment } from "@vincle/flow";
import { NativeAdapter } from "@vincle/flow/adapters";

declare function fetchPrice(symbol: string): Promise<{ value: number }>;

// A Netlify/Vercel Edge Function: both run standard Request → Response
// handlers, so this needs no platform SDK import.
export default async function handler(req: Request): Promise<Response> {
  const symbol = new URL(req.url).searchParams.get("symbol");
  if (!symbol) return new Response("Missing symbol", { status: 400 });
  // This example accepts only symbols safe to embed in a fragment id.
  if (!/^[A-Za-z0-9_-]+$/.test(symbol)) {
    return new Response("Invalid symbol", { status: 400 });
  }

  const price = await fetchPrice(symbol);
  const { url, html } = await renderFragment(
    `price-${symbol}`,
    <span>{price.value.toFixed(2)}</span>,
    { adapter: NativeAdapter },
  );

  // `url` matches the path the full build already wrote this fragment to,
  // upload `html` there (blob store, on-demand revalidation, CDN purge +
  // PUT…). The shell page that includes it never needs rebuilding.
  return Response.json({ url, html });
}
```

How you publish those bytes at `url` (a blob store, a revalidation call, a CDN
purge and re-upload) depends on the host and stays in your handler. See
[`renderFragment`](/api/flow/renderfragment) for the full API.

Fragment ids must start with a letter and contain only ASCII letters, digits,
hyphens and underscores. This example rejects symbols such as `BRK.B` or
`^GSPC` with a 400 response. To support them, map each symbol to a unique valid
id and use the same mapping in the full build and regeneration handler.
