Deploy guide · runtime = "docker"

Deploy React (Vite SPA) on Percher

Vite + React is the standard single-page-app stack — fast HMR, ES-module-native dev server, and a production build that emits a static bundle. On Percher it ships as a `runtime = "docker"` multi-stage build: Bun compiles, Caddy serves.

Why Percher fits

Multi-stage Docker build means the runtime image is tiny (~30 MB on Alpine + Caddy) — cold starts are essentially instant.
SPA routing works out of the box: the generated Caddyfile falls back to `/index.html` for unknown paths, so React Router deep links don't 404.

Quick start

bunx percher create my-app --template vite-react
cd my-app
bunx percher publish

The first command scaffolds a working React (Vite SPA) project plus a `percher.toml`. Publish builds and deploys it; the live URL prints on completion.

percher.toml

The canonical config for a React (Vite SPA) app on Percher. `bunx percher init` generates this automatically when it detects React (Vite SPA) in your project.

[app]
name = "my-app"
runtime = "docker"
framework = "vite"

[web]
port = 8080
health = "/"

Common gotchas

Vite needs a build step, so it ships as `runtime = "docker"`, not `"static"`. `bunx percher init` scaffolds the Dockerfile and Caddyfile automatically.
`VITE_*` env vars auto-forward to the build container — set them via `bunx percher env set VITE_API_URL=...` and they're baked into the client bundle on the next deploy.
API calls from the SPA go directly from the browser to your backend (Supabase, your own API, etc.) — there's no server-side proxy on the Caddy serving the static bundle.

Related docs

Ready to deploy React (Vite SPA)?

Free plan, no credit card. Live in under a minute.

← Browse all deploy guides