How to Configure Nginx for Single-Page Applications

What Are Single-Page Applications?

Single-page applications (SPAs) built with frameworks like React, Vue, or Angular use client-side routing. The server must be configured to serve the index.html file for all routes so the JavaScript router can handle navigation. Nginx is an excellent choice for serving SPAs on a Breeze.

Prerequisites

• A Breeze running Ubuntu 22.04+ with Nginx installed
• Your SPA built and ready in a directory (e.g., /var/www/myapp/dist)
• A domain name pointed to your Breeze

Step 1: Create the Nginx Server Block

sudo nano /etc/nginx/sites-available/myapp

server {
    listen 80;
    server_name myapp.yourdomain.com;
    root /var/www/myapp/dist;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }

    location /api/ {
        proxy_pass http://localhost:3000;
        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;
    }

    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff2?)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
        access_log off;
    }
}

Step 2: Enable the Site

sudo ln -s /etc/nginx/sites-available/myapp /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

Step 3: Enable Gzip Compression

In your nginx.conf or server block:

gzip on;
gzip_types text/plain text/css application/json application/javascript text/xml;
gzip_min_length 1000;
gzip_vary on;

Step 4: Add SSL with Certbot

sudo certbot --nginx -d myapp.yourdomain.com

Key Points

• The try_files directive is essential — it falls back to index.html for all routes
• API requests are proxied to your backend separately
• Static assets get long cache headers since SPA builds use hashed filenames
• Enable HTTP/2 for multiplexed asset loading on your Breeze