Deploy guides

How to deploy a React app on Stackap

To deploy a React app on Stackap you push a repository whose build script produces an index.html; the server builds it, serves it with a router-friendly fallback, and puts it on HTTPS.

Before you start

This guide is about the questions React developers actually hit, which are about routing and public values and not about the server. If your React app is Next.js, use the Next.js guide instead, because it has a server and different rules.

The two cases below are Vite and Create React App. They build differently but are served identically.

Check these in your React project

• The build script writes an index.html into dist (Vite) or build (Create React App).
• The router uses the root of the domain. If you configured a basename, remove it.
• Every value your code reads is prefixed VITE_ or REACT_APP_ and none is secret.
• API calls use an absolute URL, because the static app has no backend of its own.
• You are not relying on server components or server rendering.

What to watch while it builds

The build log should say Stackap generated an image for a single-page app and name vite or react-scripts. If it names a Node app instead, your package.json has a start script and no recognized build tool in dependencies.

After it is live, open a nested route directly and refresh. If the page loads, the fallback to index.html is working and your router can take over.

When it does not go live

A refresh on a route shows a blank page

The router has a basename that does not match the domain, so it renders nothing. Remove it.

The build stops saying no index.html was found

Your build writes to a folder that is not on the searched list. Change the output folder or bring a Dockerfile.

Values are undefined at runtime

They lacked the public prefix, so the bundler left them out.

The app shows old content after a deploy

The browser kept the previous JavaScript. Files have hashed names, so a hard refresh clears it; the HTML itself is not cached.

Steps

1. Get access, a token and an SSH key. Ask for an invitation at the contact page. You receive the API address and a token shown once. 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-react-app --name "My React App"

3. Prepare the repository. Run npm run build locally first and open the output folder. Seeing an index.html there is the single best predictor that the server build will pass.
4. Set environment variables. Set the public values that the build reads. They are written into the JavaScript files, so treat each as published.

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

5. Push. Deploy and watch the build log for the line naming the detected type.

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

6. Point your domain at it. Create the A record at your DNS provider, then attach the hostname.

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

Early-access scope

• Server components and server rendering are not served by this path.
• Unknown URLs return the app with a 200 status, not a real 404.
• Create React App projects build, but it is an old tool, so a new project should use Vite.

Questions

Last updated 2026-10-03.