# `build()`

Generate a static site from a configuration object. Returns a `GenerateStaticResult` describing what was written.

```typescript
import { build } from 'sovrium'

const result = await build({ name: 'my-site', pages: [{ name: 'Home', path: '/' }] })

console.log(result.outputDir) // "./static"
console.log(result.files.length)
```

Like `start()`, `build()` validates against `AppSchema` first and rejects with `Sovrium failed to build:` rather than emitting a partial site.

## `GenerateStaticOptions`

| Property             | Description                                               |
| -------------------- | --------------------------------------------------------- |
| `outputDir`          | Output directory. Default: `./static`.                    |
| `baseUrl`            | Base URL for sitemap and canonical links.                 |
| `basePath`           | Path prefix for subdirectory deployments.                 |
| `deployment`         | Target platform: `github-pages` or `generic`.             |
| `languages`          | Array of language codes to generate.                      |
| `defaultLanguage`    | Default language code.                                    |
| `generateSitemap`    | Generate `sitemap.xml`. Default: `false`.                 |
| `generateRobotsTxt`  | Generate `robots.txt`. Default: `false`.                  |
| `hydration`          | Emit the client-side hydration runtime. Default: `false`. |
| `generateManifest`   | Generate `manifest.json` for PWA. Default: `false`.       |
| `bundleOptimization` | Splitting strategy: `split` or `none`.                    |
| `publicDir`          | Static asset directory to copy into the output.           |

:::callout
**`outputDir` differs from the CLI.** Calling `build()` directly defaults to `./static`, relative to the working directory. `sovrium build app.yaml` instead defaults to a `dist/` directory _beside the config file_. Pass `outputDir` explicitly whenever both paths exist in one project.
:::

## `GenerateStaticResult`

| Property    | Description                                                         |
| ----------- | ------------------------------------------------------------------- |
| `outputDir` | Path to the output directory that was written.                      |
| `files`     | Every file generated during the build (HTML, CSS, assets, sitemap). |

The `files` array is the deploy manifest — enumerate it rather than re-walking the directory, since it excludes anything that was already there.

## A full static build

```typescript
import { build } from 'sovrium'
import type { GenerateStaticResult } from 'sovrium'

const result: GenerateStaticResult = await build(
  {
    name: 'my-site',
    pages: [
      {
        name: 'Home',
        path: '/',
        components: [
          { type: 'hero', content: 'Welcome' },
          { type: 'text', content: 'Built with Sovrium.' },
        ],
      },
    ],
  },
  {
    outputDir: './dist',
    baseUrl: 'https://example.com',
    deployment: 'github-pages',
    generateSitemap: true,
    generateRobotsTxt: true,
  }
)

console.log(`Wrote ${result.files.length} files to ${result.outputDir}`)
```

`deployment: 'github-pages'` adds the files that host needs — notably a `.nojekyll` marker so directories beginning with an underscore are served instead of being swallowed by Jekyll.

## Page search

If any page declares a `pageSearch` component, `build()` also runs the search indexer and writes a `sovrium-search/` directory into the output. The extra files appear in `result.files`. With no such component nothing is emitted and no indexing cost is paid — the feature is gated on the config, not on a flag.

## Related Pages

- [TypeScript API Overview](/en/docs/typescript) — `AppConfig` and the other functions.
- [Project Commands](/en/docs/cli-project) — `sovrium build` and its `SOVRIUM_*` variables.
- [SEO & Metadata](/en/docs/seo-meta) — what `baseUrl` and the sitemap feed.
- [Search Overview](/en/docs/search-overview) — the `pageSearch` component.