Static Sites Quickstart

Static Sites Quickstart#

Use a Static Site when your project produces files that can be served without a running Node or application server. The platform builds the output once per deployment and uploads the resulting directory — there is no long-lived process to keep alive and no health check to keep passing.

This quickstart covers the two things that actually cause static deployments to fail: running the wrong build command, and publishing the wrong directory.

When to use this#

Use this flow when:

• The deliverable is pre-built HTML, CSS, JS, and assets — hand-written HTML, a Vite/React build, an Astro static build, or a Next.js project configured with output: "export".
• Every page can be generated at build time. If any page needs server rendering, middleware, or API routes at request time, use Frontend App instead.

Before you begin#

• Node.js installed locally so you can verify the build produces the directory you plan to publish.
• A workspace and permission to create a project in the dashboard.
• The project’s framework confirmed (Vite, Astro, Next.js, SvelteKit with a static adapter, plain HTML).

Example: Vite and React#

From an empty parent directory, create a small Vite + React site:

npm create vite@latest my-site -- --template react
cd my-site
npm install
npm run build

What that last step does: the build script (typically vite build) produces the static output in dist. Inspect it:

ls dist
# index.html, assets/, etc.
cat dist/index.html | head -n 5

If this listing looks right locally, the identical listing on the deployment detail page should match after the dashed settings you provide.

Configure the service#

1. Select Static Site in New Project. Do not select Frontend App — a static site and a frontend runtime are distinct products even when the framework name is similar.
2. Connect a repository, folder, or ZIP archive as the source. Confirm the branch and root directory when the dashboard shows them.
3. Set Build command to npm run build. If your repository tracks only source, this rebuilds on the platform — which is the normal path. If the repository already contains the pre-built directory, you may leave the build command empty.
4. Set Publish directory to dist (for the Vite example). The platform uploads only this directory after the build finishes.
5. Deploy and open the generated hostname displayed by the dashboard. The site should load the built UI directly.

What success looks like: the deployment detail says the publish directory was found and contained index.html; the generated hostname serves the page; refreshing a client-side route works when the framework’s fallback is configured (many static hosts redirect unknown paths to index.html — add that configuration in the framework if the UI uses client routing).

Other static outputs#

The same four-field configuration (service type, build command, publish directory, environment variable scope) applies to every static framework — only the values differ.

If the application needs a runtime server after build — server rendering, API routes, middleware, @next/image optimization — use Frontend App instead of mapping a static directory over a server build.

Environment variables for static builds#

Static configuration is baked into the artifact. A public API endpoint that your framework inlines at build time (for example VITE_API_URL for Vite or NEXT_PUBLIC_API_URL for Next) must be set with a Build scope before that build runs, and changing it requires a new deployment — saving without redeploying leaves the old HTML/JS live. Never store secrets in client-inlined variables; anything with a VITE_ or NEXT_PUBLIC_ prefix is observable in the browser bundle.

Troubleshooting#

Related documentation#

• Static Sites — full description of the static service contract.
• Frontend Apps — when the app needs a running Node server.
• Deployment Troubleshooting — diagnose missing outputs vs build failures.
• Environment Variables — build vs runtime scope.