gio export

Render every page of a GioJS app to static HTML in out/, with the client chunks that hydrate it, for any static host.

npx gio export

pnpm exec gio export

yarn gio export

bunx gio export

Reference

gio export takes no options besides -h / --help. It is configured through the environment:

Option	Type	Default	Description
`GIO_APP_DIR`	`path`	`./app`	The app directory. The project root (public/, .env files) is its parent.
`GIO_OUT_DIR`	`path`	`./out`	Where the site is written.
`NODE_ENV`	`string`	`production`	`development` exports with React's development build and the `.env.development*` files; anything else (or unset) is production. Use production for anything you publish: the development build writes error details into the HTML.
`GIO_SITE_URL`	`URL`	-	The site's origin (`https://example.com`). Makes the generated `sitemap.xml` possible and adds its URL to the generated `robots.txt`. Relative URLs that `app/sitemap.ts` or `app/robots.ts` return are resolved against it.
`GIO_ENV_FILES`	`0 \| 1`	-	`0` or `false` loads no `.env` files; `1` or `true` loads them even when `[env] files = false`.

Behavior

Loads the project's .env files with the server's precedence (variables already set win). GIO_PUBLIC_* values are frozen into the output.
Renders each page through the same pipeline the server uses, running getServerSideProps at export time. A dynamic route is exported once per entry of its getStaticPaths(); without one it is skipped.
Writes out/<path>/index.html per page, out/404.html (from app/not-found, or the built-in page), the client chunks under out/_next/static/chunks/ and the stylesheets under out/_next/static/css/. Each page carries its props as JSON and hydrates, so GioLink navigation works on a static host.
Copies public/ to the root of out/ and to out/public/, as the server serves it. A rendered page wins over a public/ file with the same output path.
Writes app/sitemap.*, app/robots.* and app/manifest.* as sitemap.xml, robots.txt and manifest.webmanifest, unless public/ has the same file. Without them it generates a robots.txt that allows everything, and a sitemap.xml of every exported page when GIO_SITE_URL is set.
Never starts the Rust server, so it works without the platform binary. Route handlers, WebSockets, middleware rules, image optimization and the page cache need the server and are not part of the export.

The summary lists what was written, what ships without client JS, and what was skipped:

text

[giojs] loaded env: .env.production
[giojs] static export: /home/me/site/app → /home/me/site/out

[giojs] rendered 6 page(s):
   ✓ / (index)
   ✓ /about
   ✓ /blog
   ✓ /posts/1
   ✓ /posts/2
   ✓ /posts/3

[giojs] skipped 1:
   - /drafts/:id  -  dynamic route without getStaticPaths()

[giojs] ✔ static export complete → /home/me/site/out
[giojs]   deploy the out/ folder to any static host (Cloudflare Pages, GitHub Pages, …)

Reasons a page is skipped:

Reason	Why
`dynamic route without getStaticPaths()`	The export cannot know which params to render.
`render error: ... (ref ..., details in the error log)`	The page threw; the reference matches the logged line with the real message and stack.
`redirect (307) - server only`	A redirect needs a server to answer it.
`notFound() - nothing written`	The page called `notFound()`.
`streaming/SSE route - server only`	An event stream cannot be a file.

Examples

Export with a sitemap

bash

GIO_SITE_URL=https://example.com npx gio export

Export to another directory

bash

GIO_OUT_DIR=dist npx gio export

A static site's build script

package.json

{
  "scripts": {
    "build": "tsc --noEmit && gio export"
  }
}

npm create giojs@latest -- --static writes this script; a type error stops the build before the export.

Good to know

The exit code is 0 even when pages were skipped: read the summary, or check that the files you expect exist in CI. It is 1 when @gio.js/core or tsx is missing, a .env file cannot be parsed, or the export crashes (a route conflict, for example).
out/ is not emptied first: files from an earlier export that this one does not write stay there. Delete it in your build script if pages can disappear.
Never return secrets from getServerSideProps of an exported page: the props are in the HTML.
<GioImage> renders a plain src in an export (there is no optimizer on a static host).

Static Export - the guide
gio build standalone when you need the server
Environment Variables

Version history

Version	Changes
`v0.1.0-beta.8`	Pages hydrate (client chunks and props are exported), stylesheets and CSS Modules ship, `public/` is copied to the root, `.env` files load, `NODE_ENV` defaults to production, `app/sitemap` / `robots` / `manifest` are written, and failed routes are listed with their error reference.
`v0.1.0-beta.3`	Generates `robots.txt` and, with `GIO_SITE_URL`, `sitemap.xml`.
`v0.1.0-beta.2`	Introduced.