Deploy guides

How to deploy a Vite or React app on Stackap

To deploy a Vite or React single-page app on Stackap you push the repository; the server builds it with your build script and serves the output from nginx with an index.html fallback.

Before you start

This guide is for single-page apps whose output is a folder of static files: Vite, Create React App, Vue CLI and Parcel projects. Nothing runs on the server after the build, so there is no port to configure and no process to keep alive.

Because the output is static, any value your code reads from the environment is fixed into the files at build time and is readable by every visitor.

Check these in your Vite project

• package.json has a build script and lists vite, react-scripts, @vue/cli-service or parcel.
• No server adapter or server-rendering framework is in use. Those are a different case.
• Every variable the app reads uses your bundler's public prefix, such as VITE_, and holds nothing secret.
• A lockfile is committed.
• The app calls its API at an absolute URL, because a static app has no backend of its own.

What to watch while it builds

A static build is usually the quickest thing Stackap does, since there is no server to start and nothing to warm up. We have not benchmarked Vite builds specifically, so read the build log for your own timings.

Once live, open a deep link such as /settings directly in the browser. If it loads the app and not a 404, the index.html fallback is working.

When it does not go live

Build fails, command not found

The build script calls a tool that is only a dev dependency in the wrong group. Make sure the build tools install in the image.

Blank page after deploy

The app was built with a base path that does not match the domain. Set the base to /.

Requests to the API fail

The app calls a relative URL that no longer exists on this host. Use the absolute address of your backend.

Refreshing a route returns 404

This should not happen on the single-page path. If it does, the project was detected as a different type; check the build log's detection line.

Steps

1. Get access, a token and an SSH key. Request an invitation at the contact page. You receive the server's API address and a one-time token. Pushing uses SSH, so the public key you push with must also be registered with your organization, which an owner token can do through POST /v1/ssh-keys, or the operator can do for you.
2. Log in and create the project. Log in once, then create a project for the app.

   $ stackap login --url https://api.<your-domain> --token-stdin
   $ stackap create my-vite-app --name "My Vite App"

3. Prepare the repository. Add the project's Stackap remote and make sure your production branch is the one you push. If your app lives in a subfolder of a monorepo, move it to the repository root first, because monorepo layouts are untested.
4. Set environment variables. Set only public values. They are compiled into the files, so treat each one as published.

   $ stackap env set my-vite-app VITE_API_URL --stdin

5. Push. Deploy. Stackap generates a two-stage image: your build, then nginx.

   $ stackap deploy my-vite-app
   $ stackap logs my-vite-app --source build

6. Point your domain at it. Create the DNS record at your provider, then add the hostname so Stackap can issue a certificate.

   $ stackap domains add my-vite-app app.example.com

Early-access scope

• Static output only, so server-side rendering is out of scope.
• Unknown URLs return the app shell with a 200 status, not a real 404.
• Monorepo layouts are untested.

Questions

Last updated 2026-10-03.