# voxal build

> Bundle and validate your app to disk without deploying

`voxal build` bundles and validates your app into a single file on disk. It is fully offline:
no login and no network. Use it for CI, for inspecting the artifact, or before a deploy.

```bash
voxal build [dir] [--out <file>]
```

`dir` defaults to the current directory. The entry comes from `voxal.json` (the `main` field,
default `app.js`).

## What it does

1. Reads `voxal.json` for the entry file.
2. Runs the [bundle pipeline](#the-bundle-pipeline) with production settings.
3. Boot-validates the bundle to confirm it loads and starts.
4. Enforces the same [size limits](#size-limits) as deploy.
5. Writes the artifact and prints its path and checksum.

The output path is `--out <file>`, or `<dir>/dist/<name>.js` by default.

```text
voxal build
  bundled myapp -> dist/myapp.js
    size   18.4 KiB
    sha256 9f2c1a...e7
```

Then run [`voxal deploy`](/cli/deploy) to ship it.

## Flags

| Flag | Value | Description |
| --- | --- | --- |
| `--out` | `<file>` | Output path. Defaults to `<dir>/dist/<name>.js`. |

## The bundle pipeline

Both `build` and `deploy` use the same pipeline. Your entry file, the SDK, and any pure-JS
dependencies are bundled into one file.

- JSX is enabled in `.js` too, so `app.js` can contain JSX.
- TypeScript is transpiled (types are stripped, never type-checked).
- Production builds are minified, with `process.env.NODE_ENV` set to `"production"` so React
  builds in production mode.

The bundle is then boot-validated to confirm it loads and starts your app before it can be
deployed.

<Callout type="warn">
Apps must be pure JavaScript. Native npm modules are not supported and will fail to bundle.
</Callout>

## Size limits

| Threshold | Behavior |
| --- | --- |
| 4 MiB | Warning prints ("approaching the limit"). |
| 5 MiB (5,242,880 bytes) | Hard limit. Build fails. |

Size is measured as the UTF-8 byte length of the bundle. See [Limits](/platform/limits) for
the full picture.

---

Source: https://docs.voxal.sh/cli/build