> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sevalla.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> These are the docs for Sevalla, a platform for deploying applications, databases, static sites, object storage and load balancers. The dashboard is at https://app.sevalla.com.
> Bold text in steps is an exact dashboard label.
> To act on a Sevalla account, prefer the Sevalla MCP server (https://mcp.sevalla.com/mcp, see https://docs.sevalla.com/ai-agents/overview.md), then the Sevalla CLI (https://docs.sevalla.com/developer-tools/cli.md), then the REST API (https://api-docs.sevalla.com, OpenAPI spec at https://api.sevalla.com/v3/openapi.json).
> Every page index is at https://docs.sevalla.com/llms.txt.

# Build settings

> Set how Sevalla builds a static site: build command, Node.js version, root and publish directories, index and error files, package managers, framework defaults and the build environment.

A static site's build settings tell Sevalla how to turn the repository into the files it publishes: which Node.js version to install, which command builds the site, and which folder holds the result. The dashboard calls them the **Build strategy**. Changes apply from the next deployment.

## Build settings

| Setting | What it does | Default |
| - | - | - |
| **Build site before publishing** | Runs the install and the build command. Turn off to publish the repository's files as they are. Turning it off clears the build command and the Node version. | On |
| **Node version** | The Node.js version the build installs. See [Node versions](#node-versions). | **Latest LTS** |
| **Build command** | Runs in the root directory after the dependencies are installed, for example `npm run build`. Required while the build is on. | `npm run build` |
| **Root directory** | Where the build runs, relative to the repository root, for example `apps/docs`. Empty is the repository root. | Empty |
| **Publish directory** | The folder with the finished site, relative to the root directory, for example `dist`. Empty publishes the root directory. | Empty |
| **Index file** | The file served for `/` and for folder URLs such as `/blog/`. Required. | `index.html` |
| **Error file** | A file served for any path that has no file, for example `404.html`. Sevalla serves it with status `200`. To send a `404` status, use a [404 rule](/static-sites/redirects#custom-404-pages) instead. | Empty: Sevalla's own 404 page, with status `404` |
| Install command | API only (`install_command`): replaces the automatic install. See [Package managers](#package-managers). | Empty |

Sevalla doesn't read `engines` in `package.json`, `.nvmrc` or `netlify.toml`: everything comes from these settings.

## Update the build settings

<Steps>
  <Step title="Open the build strategy">
    In the sidebar, click **Static sites**, then click the site. Click the **Settings** tab and, under **Build**, click **Update build strategy**. The **Deployments** tab has the same **Update build strategy** button.
  </Step>

  <Step title="Change the settings">
    Update the fields, then click **Update build strategy**.
  </Step>

  <Step title="Deploy the site">
    Click the **Deployments** tab, click **Deploy now**, then click **Deploy**.
  </Step>
</Steps>

The **Build strategy** section shows the new values, and the new deployment's log starts with a **Deployment details** table that lists the branch, commit, Node version, install command, build command, root folder and out folder it used. You can't change the settings while a production deployment runs.

<Frame>
  <img className="block dark:hidden" src="https://assets.sevalla.com/screenshots/light/static-site-settings-build.png" alt="The Build strategy section of a static site's Settings tab with the build command, Node version, root directory, publish directory, index file and error file" width="1216" />

  <img className="hidden dark:block" src="https://assets.sevalla.com/screenshots/dark/static-site-settings-build.png" alt="The Build strategy section of a static site's Settings tab with the build command, Node version, root directory, publish directory, index file and error file" width="1216" />
</Frame>

## How a build runs

Each deployment runs in a new, isolated build container. The deployment's log shows each step:

1. **Fetch the source.** Sevalla clones the deployment's branch with its submodules and checks out the deployment's commit (`Fetching source code from github...`, then `Source code fetched successfully`). It downloads Git LFS objects unless [Git LFS](/static-sites/deployments#git-lfs) is off.
2. **Enter the root directory**, if one is set.
3. **Install Node.js** with nvm (`Set node version to: 22`, then `Node version set successfully`).
4. **Install dependencies** with the package manager your lockfile names (`Packages installed successfully`). See [Package managers](#package-managers).
5. **Run the build command** in bash, with `node_modules/.bin` on the `PATH` (`Running build command: npm run build`, then `Build command succeeded`). A command that exits with an error fails the deployment.
6. **Check the publish directory.** It must exist and hold at most 1 GB.
7. **Read `_redirects` and `_headers`** from the publish directory, or else the root directory. See [Redirects](/static-sites/redirects) and [Custom headers](/static-sites/headers).
8. **Upload and publish.** Sevalla uploads the files that changed since earlier deployments, then switches the site to the new deployment (`Static site has been deployed successfully`).

With **Build site before publishing** off, Sevalla skips steps 3 to 5.

### Build environment

| | Value |
| - | - |
| Operating system | Ubuntu 24.04 |
| Tools | bash, curl, Git, Git LFS, jq, OpenSSL, rsync, tar, unzip, wget, zip and `build-essential` (gcc, g++, make) |
| Node.js | Managed with nvm. Major versions 16, 18, 20 and 22 are preinstalled. |
| CPU and memory | 4 CPUs and 8 GB of memory |
| Time limit | 30 minutes. A longer build fails. |
| Output size | 1 GB for the publish directory |
| Environment variables | The site's [environment variables](/static-sites/environment-variables) for the deployment's environment (production or preview) |

Build time counts toward the company's 600 free [build minutes](/static-sites/overview#pricing-and-free-allowances) a month.

## Node versions

| Option | API value | What the build installs |
| - | - | - |
| **Latest LTS** | `lts` | The newest long-term support release at build time |
| **Latest release** | `latest` | The newest long-term support release, the same as **Latest LTS** |
| **Node 22** | `22` | The newest 22.x release |
| **Node 20** | `20` | The newest 20.x release |
| **Node 18** | `18` | The newest 18.x release |
| **Node 16** | `16` | The newest 16.x release |

Sites created before the major-version options can also show `16.20.0`, `18.16.0` or `20.2.0`, which the API still accepts. The build command, and an install command, require a Node version.

## Package managers

Sevalla picks the package manager from the lockfile in the root directory, checking in this order:

| Lockfile | Install command Sevalla runs |
| - | - |
| `yarn.lock` | `yarn install` (Sevalla installs Yarn first with `npm i -g yarn`) |
| `package-lock.json` | `npm install` |
| `pnpm-lock.yaml` | `pnpm install` (Sevalla installs pnpm first) |
| `bun.lockb` or `bun.lock` | `bun install` (Sevalla installs Bun first) |
| None | `npm install`, with the warning `There is no lock file.` |

Commit your lockfile so every build installs the same versions. To run your own install command instead, set `install_command` with [Update static site](https://api-docs.sevalla.com/v3/static-sites/update-static-site). Sevalla installs Yarn, pnpm and Bun globally before it runs it, so any of them works.

## Framework detection

When you [create a static site](/static-sites/create) from a private repository, Sevalla reads `package.json` at the root of the repository on the chosen branch. If it recognizes the framework, it turns the build on, fills in the build command and publish directory, sets the Node version to **Latest LTS** and shows **Framework detected** with the framework's name. It checks in this order and uses the first match:

| Framework | Detected when `package.json` has | Build command | Publish directory |
| - | - | - | - |
| React with Vite | `react` in `dependencies` and `vite` in `devDependencies` | `npm run build` | `dist` |
| Create React App | `react` and `react-scripts` in `dependencies` | `npm run build` | `build` |
| Gatsby | `gatsby` in `dependencies` | `npm run build` | `public` |
| Astro | `astro` in `dependencies` | `npm run build` | `dist` |
| Next.js | `next` in `dependencies` | `npm run build` | `out` |
| Elder.js | `@elderjs/elderjs` in `dependencies` | `npm run build` | `public` |
| Nuxt | `nuxt` in `dependencies` | `npm run generate` | `.output/public` |
| Parcel | `parcel` in `dependencies` or `parcel-bundler` in `devDependencies` | `npm run build` | `dist` |
| Any other project | A `build` script | `npm run build` | `dist` |

With a `yarn.lock` file, the commands are `yarn build` and `yarn generate`. Sevalla doesn't detect frameworks for public repositories, and it reads only the `package.json` at the repository root: for a site in a subfolder, fill in the fields yourself.

## Settings for common static site generators

These are each tool's usual defaults. Check your project's configuration if you changed its output folder.

| Generator | Build command | Publish directory | Notes |
| - | - | - | - |
| Angular | `npm run build` | `dist/<project-name>/browser` | Angular 16 and earlier: `dist/<project-name>` |
| Astro | `npm run build` | `dist` | Static output (the default) |
| Docusaurus | `npm run build` | `build` | |
| Eleventy | `npx @11ty/eleventy` | `_site` | |
| Gatsby | `npm run build` | `public` | |
| Hexo | `npm run build` | `public` | |
| Next.js | `npm run build` | `out` | Set `output: 'export'` in `next.config.js` for a static export |
| Nuxt | `npm run generate` | `.output/public` | |
| SvelteKit | `npm run build` | `build` | With `@sveltejs/adapter-static` |
| Vite (React, Vue, Svelte, Preact, Solid) | `npm run build` | `dist` | |
| VitePress | `npx vitepress build docs` | `docs/.vitepress/dist` | |
| VuePress 2 | `npx vuepress build docs` | `docs/.vuepress/dist` | |

### Hugo and generators outside Node.js

The build container has no Hugo, Jekyll or Python. For Hugo, install it as an npm package so the build can run it:

```bash theme={null}
npm install hugo-bin --save-dev
```

```json package.json theme={null}
{
  "scripts": {
    "build": "hugo"
  }
}
```

Then set the build command to `npm run build` and the publish directory to `public`. Hugo themes added as Git submodules work: Sevalla clones submodules with the repository. For a generator you can't install with npm, build the site yourself and commit the output, or deploy it as an [application](/applications/overview).

## Publish files without a build

When the repository already holds the finished site, turn off **Build site before publishing**. Sevalla publishes the publish directory (or the root directory, if the publish directory is empty) as it is in the repository.

## Build a site in a subfolder

For a monorepo, set the **Root directory** to the site's folder, for example `apps/docs`. The install and the build run there, Sevalla looks for the lockfile there, and the publish directory is relative to it: `dist`, not `apps/docs/dist`. To deploy only when the site's files change, add the [deploy path](/static-sites/deployments#choose-which-changes-deploy) `apps/docs/**` (deploy paths are relative to the repository root).

## What gets published

Every file in the publish directory, except:

* Anything inside `.git` or `node_modules` folders.
* Files and folders whose name starts with `.env`, and `.DS_Store` files.
* The `_redirects` and `_headers` files. Sevalla reads them instead of serving them.

Sevalla compresses text files (HTML, CSS, JavaScript, JSON, XML, SVG, TXT and TTF fonts) and serves Markdown files (`.md`, `.markdown`) as `text/markdown`.

## API and CLI

| Task | API | CLI |
| - | - | - |
| Update the build settings | [Update static site](https://api-docs.sevalla.com/v3/static-sites/update-static-site) | `sevalla static-sites update <id> --build-command "npm run build" --publish-directory dist` |
| See the current settings | [Get static site](https://api-docs.sevalla.com/v3/static-sites/get-static-site) | `sevalla static-sites get <id>` |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.