How to deploy React on Saplo (SPA and dashboard without backend)

React is the go-to choice for building interfaces today, but React itself isn't a hosting solution - it's a UI library. A built project (most often by Vite) is a handful of static HTML, CSS, and JS files that need to be exposed somewhere with correct SPA routing (fallback of all paths to index.html) and without unnecessary background processes. Standard shared hosting forces you to upload files manually via FTP and doesn't handle route fallbacks, while paid platforms charge you for every request and build. On Saplo, you deploy React like any other application from the catalog: the engine builds the project, exposes the ready-made dist directory under nginx, and takes care of route redirects itself.

Who is React on Saplo for?

Before you start the installation, check if it's a good choice for your project:

• you're building an admin panel or a customer dashboard - Saplo serves a ready-made build as static files, without its own Node server kept in memory,
• the frontend needs to connect to its own API - you set up a SPA next to the backend (Django, Node, Docker) on the same Box or separately; you enter the API address as an environment variable for the build,
• the project doesn't need server-side rendering - if SEO and SSR are important to you, check out the Next.js stack in the app catalog instead of pure React,
• you want deployments with git push instead of manually uploading files via FTP - you connect the repository once, and every push to the production branch builds and deploys a new version automatically.

Requirements

To set up React on Saplo, you need:

• A Box on any plan, even S is enough - a built SPA is a handful of static files, after the build, no Node process remains in memory, so RAM usage after installation drops to virtually zero,
• A minimum of 256 MB of free RAM for the build process itself (Vite compiles the project once, during installation and with every subsequent git push) and 2 GB of disk space,
• A domain or subdomain *.saploapp.pl included with every plan, under which the application will be hosted,
• A Git repository, if you want to use automatic deployment (optional at the start, you can also upload the application as an archive .zip via the panel).

Step-by-step installation

1. In the Saplo panel, go to App catalog and select React (under "Applications").
2. Specify the Box and application name - this creates the default subdomain <name>.saploapp.pl.
3. Choose the Node.js version for the build (18, 20, or 22, default is 20) and confirm the installation.
4. The engine scaffolds the React skeleton using Vite (the equivalent of npm create vite -- --template react), installs dependencies, and builds the project. The content of the dist directory is then placed directly into the application directory, served by nginx.
5. After the installation is complete, the domain from step 2 will display the starter Vite + React skeleton - from this point, you can deploy your own code to it.

Deploy your own code via Git

1. In the application details, find the Git / CI-CD section and click "Connect GitHub", confirm the installation of the "Saplo Deploy" application on your account or organization, and point to the repository with the React project.
2. The saplo.yaml file must be in the root directory of the repository.
3. Commit and push the saplo.yaml file to the production branch (by default main).
4. Every subsequent git push to this branch builds the project and replaces the contents of the dist directory on Box. You can see the status in the Deployments tab.
5. SPA routing (all paths fall back to index.html) is configured automatically - you don't need to add anything to nginx.

Example of a minimal saplo.yaml file for React:

name: my-project
stack: react
build:
  install: npm ci
  command: npm run build
  output: dist

React on Saplo vs. Alternatives

FAQ

Can I have multiple React applications on one Box? Yes, the App catalog allows you to set up multiple modules side-by-side, each with its own subdomain or domain, as long as there is enough RAM and disk space allocated to the plan.

What about client-side routing (React Router)? It works without additional configuration - the fallback for all paths to index.html is set up immediately upon installation.

Do I have to use Vite? The installation from the catalog scaffolds the project using Vite, but you can deploy your own project (also based on another bundler) via git, as long as the build outputs the ready files to the directory specified in build.output.

Will I get SSL and my own domain? Yes, an SSL certificate is automatic, and a *.saploapp.pl domain or subdomain is included in the price of each plan.

How do I change the Node.js version used for the build? When creating an application from the catalog, you choose 18, 20, or 22. For deployments via git, you set it using the runtime.node field in saplo.yaml.

With Saplo, you can get React up and running from scratch to a working domain in minutes, and each subsequent git push deploys a new version without manually uploading files. If your project needs SSR and better SEO, check out the Next.js stack in the same catalog.