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

# Deploy a Vite or Next.js static site with a CDN

> Put a Vite or Next.js static site on Reliant's free static hosting behind a CDN: build one release, deploy it to prod, check the live URL, then clean up.

By the end of this guide you will have a Vite single-page app live on a generated `*.sites.reliantlabs.dev` hostname, served from [Reliant hosting](https://docs.reliantlabs.io/hosting/overview.md)'s static hosting and CDN, with a recorded release you can deploy again or promote. The same steps work for a Next.js static export.

A static site is a complete Forge project with no backend. Reliant owns the bucket, the CDN and the hostname, and one static site per person is free, across the organizations you own that have no hosting plan.

## Before you begin

* Reliant v1.21.3 or later, signed in. Inside Reliant, Forge runs as `reliant forge`. This guide was run on Forge v1.6.1. Use v1.5.0 or later, the first release where `obs check` judges a static site by its browser telemetry.
* Node 20.19 or later (the Vite starter's minimum; Next.js needs 20.9) and git, with a git identity set, so Forge can make the first commit.
* An existing app instead of a new one? [Deploy without an account](https://docs.reliantlabs.io/forge/deploy-without-an-account.md) adopts a Vite or Next.js app where it stands.

**1. Create the site**

`--frontend-kind` is `vite-spa` or `nextjs`:

```bash terminal theme={null}
reliant forge project new my-site --kind site --frontend-kind vite-spa
cd my-site
```

```text Output (trimmed) theme={null}
✅ Static site 'my-site' created at my-site
   frontend "web": a Vite SPA starter at the root (path ".", builds into dist/)
   wrote the app, forge.yaml, deploy/kcl/kcl.mod, deploy/kcl/{dev,staging,prod}/main.k — no Go, no server
```

`deploy/kcl/prod/main.k` binds the frontend to hosting with `runtime = forge.OnHosted {}` and names where the build lands (`public_dir = "dist"`, or `"out"` for Next.js). `reliant forge env up dev` runs the dev server.

**2. Check that it builds as a static export**

Hosting serves files, so the build must produce plain HTML, JS and CSS:

```bash terminal theme={null}
reliant forge lint --static-export
npm run build
```

```text Output (trimmed) theme={null}
✓ static-export
✅ All 1 gating linters passed.
...
dist/index.html                   0.50 kB │ gzip:   0.29 kB
dist/assets/index-C2v5HPV7.js   294.37 kB │ gzip:  94.83 kB
✓ built in 656ms
```

For Next.js, the lint names each thing an export cannot serve, with its file and line. A Vite SPA has nothing to check there, so `npm run build` is the proof. Commit before the next step: a release from a dirty tree describes no commit.

**3. Cut a release**

Build once, push, and record every digest under a version name:

```bash terminal theme={null}
reliant forge env build prod --release v0.4.2
```

```text Output (trimmed) theme={null}
[build] web: hosted static site → registry.reliantapi.com/<org-id>/my-site/web/static.v1
[build]   web release sha256:05d3b882eaf356d8ddf13c562eba863ca8145c8813ab6e985e5faea1df4aaa55
[build] Cut release v0.4.2 (1 image(s), 0 package(s), 0 file(s))
[build]   Deploy:  forge env deploy <env> v0.4.2
```

Source maps are stored beside the release, not served. [Releases and promotion](https://docs.reliantlabs.io/forge/deploy/releases-and-promotion.md) explains what a release records.

**4. Deploy it to prod**

`--yes` means "I read the plan". Without a terminal or `--yes`, the deploy stops at the plan (exit 5) and promotes nothing. To approve a reviewed plan instead, use `--plan-only` and then `--approve <digest>`:

```bash terminal theme={null}
reliant forge env deploy prod v0.4.2 --yes
```

```text Output (trimmed) theme={null}
PLAN (approved — recording and publishing follow): promote env "prod" → release v0.4.2
  direction INITIAL  FIRST PROMOTE
  url web: https://prime-grouse.sites.reliantlabs.dev (served through the CDN edge)
Rollout of v0.4.2 to prod: SUCCEEDED
  web: serving sha256:05d3b88…
```

The first deploy took about four and a half minutes, mostly waiting on the platform's stability window.

**5. Verify the site and its caching**

```bash terminal theme={null}
curl -sI https://prime-grouse.sites.reliantlabs.dev/
curl -sI https://prime-grouse.sites.reliantlabs.dev/assets/index-WpEY6Mf_.js
reliant forge env status prod
```

```text Output (trimmed) theme={null}
HTTP/2 200
cache-control: no-cache
strict-transport-security: max-age=31536000
via: 1.1 google

HTTP/2 200
cache-control: public, max-age=31536000, immutable
age: 13

MATCH        registry.reliantapi.com/<org-id>/my-site/web/static.v1
1 match, 0 drifted, 0 missing, 0 untagged, 0 unreachable
```

HTML and `/config.js` (the per-environment runtime config) are `no-cache`, so a new release shows on the next load. Hashed assets are cached for a year, and `age` on a repeat request means the CDN edge answered. An unknown path with no extension returns `index.html` with a 200, so client-side routing works. A missing file with an extension returns 404.

**6. Check the release's health**

```bash terminal theme={null}
reliant forge obs check prod --wait --json
```

```text Output (trimmed) theme={null}
"exit_code": 2,
"verdict": "INCONCLUSIVE",
"reason_code": "no_request_telemetry",
"reason": "no request telemetry: no service sent a single server span in either window, ... and no page sent browser telemetry, so error rate and latency could not be judged. ..."
```

The check compares the 15 minutes after the promotion with the 15 before. A static site has no server, so it is judged by the telemetry its pages send from real browsers, and `curl` runs no JavaScript. With no visitors, the result is exit 2: not proven good, which is not a pass. Exit 0 is PASS and exit 1 is FAIL.

**7. Clean up**

Delete the environment when you are done with a trial site:

```bash terminal theme={null}
reliant forge env delete prod --yes
```

```text Output (trimmed) theme={null}
Deleted env prod; the platform is tearing it down, its databases included.
```

Within a minute the hostname answered `404`. The project's release images stay in the registry. They belong to the project, not the environment.

## The free tier and a second environment

Without app hosting billing, the free tier covers one static site, counted across environments, so deploy prod first. A second environment's deploy is recorded but held: `env deploy` prints the billing link and exits **7**, and the site goes live by itself once billing is set up, with nothing to re-run. With billing in place, it deploys like the first. [Queued deploys](https://docs.reliantlabs.io/hosting/overview.md#queued-deploys) has the details and the free tier's storage and traffic limits.

## What this does not do

* **No rollback command.** To go back, deploy an earlier release, or cut a new one with the fix. [Releases and promotion](https://docs.reliantlabs.io/forge/deploy/releases-and-promotion.md) covers rollback floors.
* **No code at request time.** There are no server-rendered pages, API routes or middleware. A site that needs a backend gets its own Forge project, reached by URL.
* **No redirects of your own.** Host redirects such as www to the bare domain cannot be declared. Response headers can: a `_headers` file at the root of the build (`public/_headers` in a Vite app, which the build copies into `dist/`) adds headers such as a `Content-Security-Policy`, in the Netlify and Cloudflare Pages format. See [the static edge and origin](https://docs.reliantlabs.io/deep-dives/inside-reliant-hosting.md#the-static-edge-and-origin).
* **Replay is masked and off until consent.** The starter's `main.k` sets `_session_replay = True`, but nothing records until a visitor consents, and text and inputs are always masked. Set it to `False` to turn replay off. See [Session timelines and replay](https://docs.reliantlabs.io/hosting/observability/session-timelines.md).

## Troubleshooting

> [accordion] static-export-dynamic-segment: /posts/\[slug] is a dynamic route (\[slug]) with no generateStaticParams
>
> A Next.js export renders every page at build time. If the values are known at build time, export `generateStaticParams()` returning each one. Otherwise, move the id into the query string (`/posts/view?slug=…`) and read it with `useSearchParams`.

> [accordion] CutRelease failed (HTTP 404, not\_found) ... release, environment or deployment not found
>
> On Forge v1.6.1, `env build --release` failed this way when another project in the same organization had already cut that version name. The run behind this guide hit it with `v0.1.0`. Cutting the release under a version name no other project in the organization has used worked.

## Next steps

> [card] [Releases and promotion](https://docs.reliantlabs.io/forge/deploy/releases-and-promotion.md)
>
> How a release is built once and promoted by digest, with approvals and rollback floors.

> [card] [Promote staging to production](https://docs.reliantlabs.io/guides/hosting/promote-release-staging-to-production.md)
>
> Deploy the exact release staging runs to prod with `--from staging`.

> [card] [Custom domains](https://docs.reliantlabs.io/hosting/custom-domains.md)
>
> Serve the site on a hostname you own, with automatic HTTPS.

> [card] [Deploy without an account](https://docs.reliantlabs.io/forge/deploy-without-an-account.md)
>
> Publish an existing app with no signup and hand over a claim link.


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