# Static Site Generation

> Render every route to HTML at build time and deploy the output as plain files with no server runtime.

Source: [https://askrjs.com/docs/rendering/static-site-generation](https://askrjs.com/docs/rendering/static-site-generation)

Status: stable. Packages: @askrjs/askr/ssg, @askrjs/cli.

**Published packages are authoritative.** Examples may lag behind a published contract. When guidance differs, verify the exports and TypeScript declarations in your installed package, then file an issue.

## Example

Export the route registry, document renderer, and assets from ssg.config.ts, then let the CLI enumerate every registered static route.

```tsx
export const staticConfig = {
  registry,
  outputDir: 'dist',
  document: renderDocument,
  assets: [{ from: resolve('public'), to: '.' }],
};

// askr ssg --config ./ssg.config.ts --output ./dist
```

## Static registry

`createStaticGen` from `@askrjs/askr/ssg` takes the `registry: RouteRegistry` captured with `createRouteRegistry()` — the same registry shape used by SSR and boot. Define the route handler with the router DSL, and use its `entries()` option for parameterized paths like `/posts/{slug}` so generation and runtime consume one route source.

## Document rendering

`SSGOptions` accepts the same `document: DocumentRenderer` used by SSR, plus a `seed` for deterministic output and `dataOverrides` keyed by route for supplying resource data without a live backend. Calling `.generate(options)` renders every configured route and returns an `SSGResult` with per-route status (`success`, `error`, `skipped`, `removed`) and the reason each route was or wasn't rebuilt — useful for `SSGMode: 'incremental'` runs driven by `changedKeys` or `changedRoutes`.

## Assets and output

`outputDir` is where generated HTML and `metadata.json` land; `assets: readonly SSGAssetSource[]` lets you copy additional files or directories in alongside them, each with a `from` source and an optional `to` destination relative to `outputDir`. The CLI wraps this as `askr ssg --config <path> --output <dir> [--incremental]` so a build script doesn't need to call `createStaticGen` directly.

## 404 and hosting

There's no dedicated 404 API in `@askrjs/askr/ssg` — a not-found page is just another `RouteConfig` entry you generate to a path like `/404`, and your static host is responsible for serving it as the fallback for unmatched paths (most static hosts look for `404.html` or a configured error-document setting). Routes with `auth` requirements or runtime-only `policies` are excluded from prerendering by default, since SSG can't evaluate a per-request auth check at build time.

## Documentation navigation

[Previous](https://askrjs.com/docs/rendering/selective-hydration/index.md) | [Next](https://askrjs.com/docs/server/index.md)