Deploy a React App for Free on RunxBuild: 2026 Guide

To deploy a React app for free, push your project to GitHub, create a Static Website in RunxBuild, set the build command to npm install && npm run build, set the publish directory to dist for Vite or build for Create React App, then deploy. RunxBuild builds the project, publishes the static files, gives you a live route, and can redeploy on future pushes.

That is the short version. The slightly longer version is where most broken deploys live: wrong output folder, missing environment variables, React Router refresh errors, and local builds that work only because your laptop is being generous.

Table of contents

• What this guide covers
• Before you deploy
• Step 1: Push your React app to GitHub
• Step 2: Create a Static Website in RunxBuild
• Step 3: Use the right React build settings
• Step 4: Add environment variables
• Step 5: Deploy and verify the live site
• Step 6: Handle React Router and page refreshes
• Step 7: Add a custom domain
• Troubleshooting failed React deploys
• FAQ

What this guide covers

This is a practical tutorial for deploying a React single-page app as a static website on RunxBuild: short answer first, then repository setup, build settings, routing notes, domains, and troubleshooting.

You can use it for:

• Vite React apps
• Create React App projects
• React Router single-page apps
• Marketing sites, dashboards, docs, and frontend prototypes
• quickly built React frontends that suddenly need a real URL

If your React app also needs an API, background jobs, or a database, deploy the frontend as a static website first. Then add a backend service or managed database from the same RunxBuild dashboard. A prototype without logs is just a mystery with a URL.

Useful internal docs:

• RunxBuild static site documentation
• Build settings for static sites
• Custom domains on RunxBuild
• Deploy a Node.js API on RunxBuild

Before you deploy

Before creating the RunxBuild project, confirm the app builds locally.

npm install
npm run build

A production React build creates static files. RunxBuild publishes those files behind a live route.

Check your output folder:

React setup	Common build command	Common publish directory
Vite React	npm install && npm run build	dist
Create React App	npm install && npm run build	build
Custom React setup	Your build script	Check your config

The publish directory matters. If you deploy ./ when the compiled files are actually inside dist, the deploy may finish but the browser will not get the app you expect.

For framework background, see the official React documentation and the Create React App deployment notes.

Step 1: Push your React app to GitHub

RunxBuild deploys from a GitHub repository, so the first step is getting your app into a repo.

git init
git add .
git commit -m "Initial React app"
git branch -M main
git remote add origin https://github.com/YOUR-USER/YOUR-REPO.git
git push -u origin main

If your project already lives on GitHub, make sure the latest working code is pushed to the branch you plan to deploy.

Do not commit .env files with secrets. Add them in RunxBuild as environment variables instead.

Step 2: Create a Static Website in RunxBuild

Open the RunxBuild dashboard and create a new Static Website resource.

Choose your GitHub repository and select the branch you want to deploy. For most projects, that branch is main.

Use a clear resource name, such as:

react-dashboard

RunxBuild will use that project configuration for builds, deploy logs, and future redeploys.

Step 3: Use the right React build settings

Set the deployment fields like this for most Vite React apps:

Root Directory: ./
Build Command: npm install && npm run build
Publish Directory: dist

For Create React App, use:

Root Directory: ./
Build Command: npm install && npm run build
Publish Directory: build

If your React app is inside a monorepo, change the root directory to the app folder:

Root Directory: apps/web
Build Command: npm install && npm run build
Publish Directory: dist

The top deployment guides all spend time on build output because this is the boring setting that breaks the exciting launch. Check it once. Save yourself the dramatic detective montage.

Step 4: Add environment variables

Many React apps use public environment variables for API URLs, analytics IDs, feature flags, or client-side configuration.

For Vite, browser-exposed variables usually start with VITE_:

VITE_API_URL=https://api.example.com

For Create React App, browser-exposed variables usually start with REACT_APP_:

REACT_APP_API_URL=https://api.example.com

Add these in RunxBuild before deploying. Then rebuild the site so the variables are included in the production bundle.

Important: anything exposed to a React frontend can be seen by users in the browser. Do not put database passwords, private API keys, or server-only secrets in a static React app. If you need private secrets, put them in a backend service and call that service from the frontend.

Step 5: Deploy and verify the live site

Click Deploy Website.

RunxBuild will clone the repository, install dependencies, run the build command, and publish the output directory. When the deployment finishes, open the live route.

Check these items before calling it done:

• The homepage loads.
• Hard refresh works.
• Assets load without 404 errors.
• Navigation works.
• Forms submit to the correct API.
• The deployed site uses the right environment variable values.
• The browser console has no production errors.

If the app came together quickly, this is where you slow down for five minutes. Fast prototypes are useful. Production still wants receipts.

Step 6: Handle React Router and page refreshes

React Router apps often work locally but fail when you refresh a nested route like /dashboard/settings.

That happens because the browser asks the server for /dashboard/settings. A static host may look for a real file at that path. For a single-page app, the server should return index.html and let React handle the route.

RunxBuild supports static routing rules for this. See rewrites for static sites and add a fallback rule so unknown routes serve the React entry file.

The general SPA rule is:

/* -> /index.html

For deeper context on the browser history behavior behind this, see MDN’s History API documentation.

Step 7: Add a custom domain

After the first deploy works, add your custom domain.

In RunxBuild, open the static site settings, add the domain, and follow the DNS instructions. Keep the generated RunxBuild route available while DNS propagates so you can verify the site independently.

A good domain rollout order is:

1. Deploy on the default RunxBuild route.
2. Test the app.
3. Add the custom domain.
4. Update DNS.
5. Test HTTPS after propagation.

Do not debug DNS and React build errors at the same time. That is how a simple deploy turns into a group chat with three theories and no evidence.

Troubleshooting failed React deploys

Build fails with missing dependencies

Run npm install locally, commit the updated package-lock.json, and deploy again. The lockfile helps the remote build install the same dependency tree.

Deploy succeeds but the page is blank

Check the publish directory first. Vite usually uses dist. Create React App usually uses build. Also open the browser console and look for missing JavaScript or CSS files.

Environment variables are undefined

Confirm the prefix. Vite needs VITE_ for browser variables. Create React App needs REACT_APP_. After changing variables, trigger a new build.

Refreshing a nested route returns 404

Add an SPA fallback rewrite to serve index.html for unknown routes. This is common with client-side routing.

The app calls the wrong API

Check the deployed environment variable value. If the API uses private credentials, move that call into a backend service instead of exposing secrets in the React bundle.

FAQ

How do I deploy a React app for free?

Push the React project to GitHub, create a Static Website in RunxBuild, set the build command to npm install && npm run build, choose dist or build as the publish directory, and deploy. RunxBuild will build and host the static output for free within the included monthly allocation.

Where can I host a React app for free?

You can host a React app for free on platforms that support static site deployment from Git. RunxBuild is a good fit when you want the React frontend, backend services, databases, logs, and domains in one dashboard.

What is the build command for a React app?

For most React projects, use npm install && npm run build. Vite React apps usually output to dist, while Create React App outputs to build.

Can I deploy a React Router app as a static site?

Yes. You usually need an SPA fallback rewrite so deep links like /account/settings serve index.html instead of returning 404. React then handles the route in the browser.

Should React environment variables be secret?

No. Variables included in a static React build are visible in the browser. Use them for public configuration, not passwords or private API keys.

Do I need a backend for a React app?

Not always. A static React app is enough for portfolios, docs, landing pages, and many dashboards that call public APIs. Add a backend service when you need private secrets, database writes, authentication logic, webhooks, or server-side jobs.

About the author

Written by Sean, Platform Writer at RunxBuild. Last updated: June 6, 2026.