React SPA on CloudMagnus

React Single-Page App backed by static hosting. Build locally with Vite or Create React App or whatever your bundler is; ship the contents of dist/ via SFTP.

What our scaffold installs

  • A placeholder htdocs/index.html that says "Build your React app locally and SFTP the contents of dist/ to htdocs/."
  • nginx vhost configured for static file serving
  • No Node runtime, no build pipeline, no npm install on the server
  • No database

React SPA is internally a "static" site type with a placeholder geared toward SPAs. The hosting infrastructure is identical to the static type.

What you do next

  1. Build your app locally: npm run build (or whatever your bundler's command is). For Vite, the output is dist/; for Create React App, build/.
  2. SFTP into your site. Delete the placeholder htdocs/index.html.
  3. Upload the contents of your build directory (not the directory itself) into htdocs/. So dist/index.html ends up at htdocs/index.html.
  4. Visit your domain. Your SPA is live.

Client-side routing

SPAs typically route in JavaScript (React Router, etc.). When a user navigates to example.com/dashboard directly (or refreshes the page on a non-root route), nginx looks for a file called dashboard and returns 404 by default.

To fix this, we need to configure nginx to fall back to index.html for any unknown route. Contact support and we'll add the SPA fallback to your vhost. This isn't a per-site dashboard setting yet; it's a one-line vhost edit.

Build pipeline

CloudMagnus does NOT run npm run build for you. Build locally or in CI; ship artifacts.

If you'd like a CI integration (GitHub Actions deploying via SFTP on push), the standard pattern is the SamKirkland/FTP-Deploy-Action or any sftp-deploy GitHub Action. Configure with the credentials from the dashboard.

API backends

If your SPA needs a backend API, host it as a separate site (Node.js, Python, or PHP type) at a subdomain like api.example.com, and configure CORS so your SPA can talk to it. Or use a separate hosting provider for the API and just point the SPA at it.

Caching

nginx serves static files with sensible cache headers. Bundlers typically hash filenames (index-abc123.js) so cache invalidation happens automatically when you redeploy with new hashes. The index.html itself is served with shorter cache TTLs so users pick up the new HTML quickly.

Common React SPA issues

White page

Open the browser dev tools console. Almost always a JavaScript error in your build (failed to load a chunk, syntax error in vendor code, missing environment variable at build time).

Refresh on non-root route gives 404

SPA fallback isn't configured. Contact support; we'll add it.

"Mixed content" warnings

Your SPA loaded over HTTPS but is fetching something over HTTP. Update the API URLs in your build config.