skills.rest
freedomw1987
freedomw1987COMMUNITY
Explore all skills by this author →
𝕏@davidaasmGitHub

vite-spa-nginx-deployment

Configure nginx to serve Vite React SPAs with HashRouter and static caching.

2|Updated May 10, 2026
Search Tags:#devops#react#vite#nginx#static hosting#reverse proxy#spa deployment
One-click install
npx skills add https://github.com/freedomw1987/tree_monstor --skill vite-spa-nginx-deployment
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: vite-spa-nginx-deployment
Source: https://github.com/freedomw1987/tree_monstor/tree/main/skills/vite-spa-nginx-deployment
Command: npx skills add https://github.com/freedomw1987/tree_monstor --skill vite-spa-nginx-deployment

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Deploying a Vite React SPA with nginx as a static file server is prone to common, hard-to-debug issues: broken client-side routing (e.g., 404 errors on page refresh, broken password reset email links), nginx permission errors that block access to static files, stale cached assets after deployments, infinite rewrite loops for SPA fallback, and misconfigured backend proxies that return 404s for API routes.

Core Features & Use Cases

  • Stable nginx SPA Configuration: Provides a named location pattern for SPA fallback that avoids infinite rewrite cycles, plus static asset caching rules for optimal performance.
  • React Routing Fix: Guides you to switch to HashRouter to ensure email links (like password reset or email verification) work correctly without server-side route support.
  • Permission & Deployment Guidance: Includes steps to fix www-data file permissions for nginx access, Docker deployment workflows to avoid stale assets, and reverse proxy configuration for separate backend API services.
  • Use Case: For example, if you are deploying a customer-facing React app built with Vite, this skill ensures users can refresh pages, click email links, and access backend APIs without 404 errors or permission issues.

Quick Start

Use the vite-spa-nginx-deployment skill to configure nginx to serve your Vite React SPA's dist/ folder, set up HashRouter for email links, fix www-data file permissions for the static file directory, and deploy the app without common routing or permission errors.

Frequently Asked Questions about vite-spa-nginx-deployment

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
Why does my Vite React SPA return 404 on page refresh with nginx?▼

Vite React SPA 404 errors on refresh occur because nginx lacks a stable SPA fallback pattern. You need a named location block for SPA fallback to avoid infinite rewrite cycles and correctly serve your dist/ folder static files.

How do I fix broken password reset email links in my Vite React app?▼

Broken email links in a Vite React app happen when server-side routing is unsupported. Switching to HashRouter ensures client-side routes in email links work correctly without requiring server-side route support.

How do I resolve nginx permission errors when serving Vite static files?▼

Nginx permission errors blocking Vite static files require fixing www-data file permissions. You must grant the nginx www-data user access to the static file directory to serve the dist/ folder correctly.

How do I configure nginx reverse proxy for backend API routes in a Vite SPA?▼

Configuring an nginx reverse proxy for a Vite SPA routes backend API requests to a separate service. This prevents misconfigured backend proxies from returning 404s for API routes while serving static assets.

How do I prevent stale cached assets after deploying a Vite app in Docker?▼

Preventing stale cached Vite assets in Docker requires a proper deployment workflow. Configure static asset caching rules in nginx alongside your Docker deployment workflow to ensure users receive fresh assets.

Do I need to change my React Router configuration to deploy a Vite SPA on nginx?▼

Deploying a Vite SPA on nginx requires routing changes for email links. You must switch to HashRouter to ensure password reset and verification links work without server-side route support.

Related Skills

Explore More Software Engineering Skills→
TETRA2000TETRA2000

export-html

Export React/Vite pages as self-contained HTML files with inlined CSS and JavaScript.

Community
Advanced
MaVoid-TeamMaVoid-Team

deployment-skill

Generate Docker, Nginx, and SSL deployment configurations for production servers.

Official
Intermediate
JansenAnalyticsJansenAnalytics
5

nginx-caddy

Configure Nginx or Caddy as a secure reverse proxy with SSL/TLS.

Community
Intermediate
haotoolhaotool
2

vite-react-best-practices

Document Vite and React SPA deployment, caching, and performance rules.

Official
Advanced