Deploying Vite + React App on Plesk: “Application Startup File” missing or 404 on refresh

by

Summary

Deploying a Vite + React app on Plesk resulted in a 404 error on route refresh due to missing history fallback configuration. The issue arose from treating the app as static files without proper client-side routing support.

Root Cause

  • Missing History Fallback: React Router’s client-side routing requires a fallback to index.html for non-root routes, which wasn’t configured.
  • Incorrect Deployment Strategy: Serving the dist folder as static files without handling SPA routing led to 404 errors on refresh.

Why This Happens in Real Systems

  • Static File Servers: Servers like Plesk’s default web server treat URLs as file paths, causing 404s for non-existent files (e.g., /contact).
  • SPA Routing: React Router handles routing client-side, but servers need to redirect unknown routes to index.html.

Real-World Impact

  • Broken Navigation: Users cannot refresh or directly access deep routes (e.g., /contact), leading to poor UX.
  • SEO Issues: Search engines may fail to index routes due to 404 errors.

Example or Code (if necessary and relevant)

# Nginx configuration for history fallback
location / {
  try_files $uri $uri/ /index.html;
}

How Senior Engineers Fix It

  • Configure History Fallback: Use .htaccess (Apache) or nginx.conf (Nginx) to redirect unknown routes to index.html.
  • Serve as Static Files: Deploy the dist folder without enabling Node.js support in Plesk.
  • Example Nginx Config: Add try_files $uri $uri/ /index.html; to handle SPA routing.

Why Juniors Miss It

  • Assumption of Static Hosting: Juniors often assume static hosting works for SPAs without understanding routing requirements.
  • Lack of Server Config Knowledge: Limited experience with web server configurations leads to overlooking history fallback.
  • Overcomplicating with Node.js: Unnecessarily setting up a Node.js server for a static SPA deployment.

Leave a Comment