Nginx for a React or Vite single-page app: routes, caching and an API proxy

1. Build and upload

npm ci
npm run build
sudo mkdir -p /var/www/example.com
sudo rsync -a --delete dist/ /var/www/example.com/

Vite and modern React setups write to dist/, while Create React App writes to build/. Upload what’s inside that folder. Nginx doesn’t look in subfolders, so with index.html a level down, you get a 403 Forbidden.

Nginx’s user has to be able to read those files, and the folders above them too. The chmod Calculator can help with the numbers.

sudo chown -R root:www-data /var/www/example.com
sudo find /var/www/example.com -type d -exec chmod 755 {} +
sudo find /var/www/example.com -type f -exec chmod 644 {} +

2. Get HTTPS, and turn it on

sudo certbot certonly --standalone -d example.com \
  --pre-hook "systemctl stop nginx" --post-hook "systemctl start nginx"
sudo ln -s /etc/nginx/sites-available/example.com /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

If that fails, see Certbot failed to authenticate.

3. Check all three cases

curl -I https://example.com/                        # 200, no-cache
curl -I https://example.com/dashboard               # 200: that's the fallback working
curl -I https://example.com/assets/index-abc123.js  # 200, immutable
curl -I https://example.com/assets/missing.js       # 404, not index.html

That last line is why /assets/ has its own try_files. With the fallback, a missing script answers 200 with HTML, and browsers then complain about a wrong MIME type: Expected a JavaScript module script but the server responded with a MIME type of "text/html". You’ll see that right after a deploy too, when someone’s old page asks for a file that’s gone.

4. Send /api to your backend

Keeping the API on the same domain avoids CORS altogether. Add this before location /, and your app can call /api/items:

location /api/ {
    proxy_pass http://127.0.0.1:3000;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

Without a trailing / on proxy_pass, your backend sees the path as it is, /api/items. With http://127.0.0.1:3000/, it sees /items. If it’s down, you’ll get a 502 Bad Gateway.

5. Under a subpath, like /app

The build has to know, or it looks for its files at the root. In vite.config.js, set base: '/app/', and in React Router, set basename="/app". Then:

location /app/ {
    alias /var/www/example.com/;
    try_files $uri $uri/ /app/index.html;
}