Enabling Hot Module Replacement (HMR) in Vite When Using an NGINX Reverse Proxy

Aron Schüler Published Jul 29, 2024

Intro

Hot Module Replacement (HMR) is a feature in modern web development tools that allows modules to be updated in the browser without a full refresh. This feature is particularly useful during development as it speeds up the feedback loop, allowing developers to see changes almost instantly and not loose state in their components. Vite, a popular build tool and development server, supports HMR out of the box. However, when using Vite behind an NGINX reverse proxy, some additional configuration is needed to ensure HMR works correctly. In this post, I’ll show you how to enable HMR in Vite behind an NGINX reverse proxy.

Step-by-Step Guide

Set Up Vite Development Server

You should have your project already set up with Vite. But you can of course create a new Vite project with the following commands:

npm create vite@latest my-vite-project
cd my-vite-project
npm install
npm run dev

This will start the Vite development server on the default port 5173.

Configure NGINX as a Reverse Proxy

Assuming you have NGINX installed and running, you need to create or modify your NGINX configuration file to set up the reverse proxy. Here’s a sample configuration:

server {
    listen 80;
    server_name myfrontend.localhost;
 
    location / {
        # If you are running this in docker, you might need to change
        # localhost to the container name of your vite server.
        proxy_pass http://localhost:5173;
        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;
 
        # Enable WebSocket support
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "Upgrade";
    }
}

This configuration forwards all traffic from myfrontend.localhost to your Vite development server running on localhost:5173. The key lines here are the ones setting the Upgrade and Connection headers, which are necessary for WebSocket support, enabling HMR to function properly.

The two headers are required since WebSockets start as an HTTP request and then upgrade to a WebSocket connection. Without these headers, NGINX would not pass the WebSocket upgrade request to the Vite server. The Upgrade header tells NGINX to upgrade the connection to a WebSocket connection, and the Connection header specifies that the client wants to upgrade the connection and it should therefore be kept open.

Reload NGINX Configuration

After updating the NGINX configuration file, you need to reload NGINX to apply the changes. If you run your nginx locally, you can do this with the following command:

sudo systemctl reload nginx

You can also quickly run a docker container with the nginx.conf mounted and port 80 mapped to your local machine:

docker run --name my-nginx -v ./nginx.conf:/etc/nginx/nginx.conf:ro -p 80:80 -d nginx

Verify HMR Functionality

With your Vite development server running and NGINX properly configured, open your browser and navigate to http://myfrontend.localhost. Make changes to your Vite project files and verify that the updates are reflected in the browser without a full page reload.

If HMR is not working, check the browser console for errors and ensure that WebSocket connections are being established correctly. You can also review the NGINX error logs for any potential misconfigurations.

Conclusion

Setting up Hot Module Replacement (HMR) in Vite behind an NGINX reverse proxy involves the set up of, primarily to support WebSockets. By following the steps outlined in this guide, you can ensure a smooth development experience with instant feedback on your changes. Properly configuring NGINX to handle WebSocket connections is crucial for HMR to function correctly.

We hope this guide has been helpful. If you have any questions or run into issues, feel free to ask in the comments below or share your experiences. Happy coding!