Setting Up NGINX for Single Page Applications (SPA) with Vite

When developing modern web applications, Single Page Applications (SPAs) have become a popular architecture choice. Frameworks like React, Vue.js, and Svelte provide seamless user experiences by loading only the necessary content for each view. These SPAs are often bundled with tools like Vite, which optimize the development and production build process.

However, when deploying these SPAs, you need a web server that can efficiently serve your application. NGINX is one of the most widely used web servers for such purposes due to its performance and flexibility.

In this blog post, we’ll walk through how to set up NGINX to serve an SPA built with Vite.

Prerequisites

Before we get started, here’s what you’ll need:

A server running NGINX.
Your Vite project built and ready for deployment.
Basic knowledge of NGINX and how to configure it.

If you don’t have NGINX installed, you can install it on your system with the following commands:

For Ubuntu:

bashCopysudo apt update
sudo apt install nginx

For CentOS:

bashCopysudo yum install nginx

Step 1: Build Your Vite Application

Once you’ve developed your SPA with Vite, it’s time to create the production build. Vite makes this process super easy by providing a build command that compiles your project into optimized static files.

Run the following command in your project’s root directory:

bashCopynpm run build

This will generate a dist/ folder containing your production-ready files, including index.html, JavaScript, and CSS assets. These files are what you will be serving with NGINX.

Step 2: Install and Configure NGINX

Once NGINX is installed, you need to configure it to serve your Vite application. You’ll modify the default configuration file or create a new server block to point to the dist/ directory generated by Vite.

Navigate to NGINX’s Configuration Directory: Typically, NGINX configurations are located in /etc/nginx/. The default site configuration is often found in /etc/nginx/sites-available/ on Debian-based systems or /etc/nginx/conf.d/ on Red Hat-based systems.
Edit NGINX’s Configuration: Let’s assume the production build of your Vite project is located at /var/www/my-vite-app/dist/. You’ll create a new server block configuration for your application. Open the NGINX configuration file for editing. For example: bashCopysudo nano /etc/nginx/sites-available/my-vite-app
Configure NGINX to Serve the SPA: Here is an example configuration for serving a Vite-based SPA: nginxCopyserver { listen 80; server_name my-vite-app.com; # Root directory for your built Vite application root /var/www/my-vite-app/dist; # The default index file to load index index.html; # Serve the main SPA index file for any route location / { try_files $uri $uri/ /index.html; } # Optional: Add headers for caching and security location ~* \.(?:ico|css|js|json|map|woff2|ttf|eot|svg|png|jpg|jpeg|gif|webp|avif)$ { expires 1y; add_header Cache-Control "public, no-transform"; } # Optional: Error page redirection (e.g., for 404) error_page 404 /404.html; location = /404.html { root /var/www/my-vite-app/dist; internal; } } Here’s a breakdown of what the configuration does:
- server_name: Replace my-vite-app.com with your domain name or IP address.
- root: Points to the location where your Vite dist/ folder is stored.
- location /: The try_files directive ensures that all routes in your SPA are redirected to index.html. This is important because SPAs handle routing client-side, and we need to let NGINX serve the index.html file for any unknown URL.
- Cache Headers: Static assets (like images, CSS, and JS) are cached for 1 year to improve performance.
- Error Page: Optionally, you can configure a custom 404 error page.

Step 3: Enable the Site and Restart NGINX

Create a Symlink to Enable the Site: If you’re using Debian-based systems (like Ubuntu), you will need to create a symlink to the sites-enabled/ directory. This tells NGINX to use the configuration you just created. bashCopysudo ln -s /etc/nginx/sites-available/my-vite-app /etc/nginx/sites-enabled/ If you’re on a Red Hat-based system, you may just need to modify the configuration in /etc/nginx/conf.d/ and no symlink is required.
Test NGINX Configuration: Before restarting NGINX, it’s a good practice to check if the configuration file is valid. bashCopysudo nginx -t If there are no errors, you should see the message: nginx: configuration file /etc/nginx/nginx.conf test is successful.
Restart NGINX: Finally, restart NGINX to apply the changes: bashCopysudo systemctl restart nginx Or, if you’re using older versions of NGINX: bashCopysudo service nginx restart

Step 4: Verify the Deployment

Open your web browser and navigate to your domain (e.g., http://my-vite-app.com). If everything is set up correctly, you should see your Vite application being served by NGINX.

Optional Enhancements

SSL Configuration (HTTPS): If you want to serve your application over HTTPS, you can set up SSL using Let’s Encrypt for a free certificate. You can use tools like certbot to automate the process of obtaining and renewing SSL certificates. Example of enabling SSL: nginxCopyserver { listen 443 ssl; server_name my-vite-app.com; ssl_certificate /etc/letsencrypt/live/my-vite-app.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/my-vite-app.com/privkey.pem; # Same settings as above for serving the SPA }
Load Balancing (Advanced): For high-traffic applications, consider using NGINX as a reverse proxy to load balance multiple backend servers or APIs.
Compression: Enable gzip compression in NGINX to reduce the size of your assets and improve performance. nginxCopygzip on; gzip_types text/plain application/javascript text/css application/json;

Conclusion

NGINX is an excellent choice for deploying SPAs built with modern tools like Vite. By following this guide, you can efficiently serve your application, ensuring optimal performance for users. Remember to always optimize your configurations for caching, security, and compression, especially in production environments.

Happy deploying! 🚀

Tech Wizard