How to Deploy a Vite React App using Nginx server?

6 min readAug 19, 2024

Deploying a React application is an essential step in making your project accessible to users on the web. Whether you’re building a simple portfolio or a complex web application, deploying it efficiently ensures that your users have a smooth experience. In this article, we’ll walk through the steps to deploy a React app using Nginx server.

Prerequisites

Before we begin, make sure you have the following:

Docker, Node.js and npm installed on your development machine.
Basic knowledge of Docker and Nginx.
A React app built with Vite.

1. Get Your React App Project

The first step is to build your React app for production. You can either use your existing React project or clone the example project from the repository linked below:

https://github.com/Dev-Mus/deploy-vite-app-using-nginx

The repository contains a simple example of a Vite-powered React app with three pages created using React Router: `/home`, `/about`, and `/404`. Vite is known for its optimized build process, focusing on speed and performance, making it an excellent choice for modern web applications.

2. Configure the Base Name and Build Your Application

Before deploying your React app, it’s important to configure the base name of your application to ensure that all routes work correctly in a production environment.

Update vite.config.js:
Open your vite.config.js file and add the base property to define the base URL for your app. This is particularly useful if your app will be served from a subdirectory on your server.

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [react()],
  server: {
    // Specify the development server port
    port: 3001,
  },
  // Base name of your app
  base: "/", // Replace this with the subdirectory path if needed
});

Run the Build:
Once you’ve configured the base name, proceed to build your React app for production. You can do this by running the following command in your terminal:

npm run build

This will generate an optimized build of your application in the dist directory, which is ready to be served by Nginx.

3. Set Up Nginx Configuration

To serve your React app with Nginx, you’ll need to configure Nginx to handle all routes and serve the correct files. Follow these steps to create the necessary configuration:

Create the Nginx Configuration File:
In the root level of your project, create a new folder named nginx. Inside this folder, create a file called default.conf and add the following Nginx configuration to it:

## nginx/default.conf
server {
  # Nginx listens on port 80 by default. You can change this if needed.
  listen 80;

  # Specifies your domain. Use "localhost" for local development or your domain name for production.
  server_name localhost;

  # The root directory that contains the `dist` folder generated after building your app.
  root /usr/share/nginx/html;
  index index.html;

  # Serve all routes and pages
  # Use the base name to serve all pages. In this case, the base name is "/".
  location / {
    try_files $uri /index.html =404;
  }

  # Example: If your base name is "/example", the location block will look like this:
  # location /example {
  #   rewrite ^/example(/.*) $1 break;
  #   try_files $uri /index.html =404;
  # }
}

4- Set Up the Dockerfile to Build Your Application

To containerize your React app and deploy it using Nginx, you’ll need to create a Dockerfile that defines the build and production environments. Follow these steps to set up your Dockerfile:

Verify Your Node.js Version:
Before setting up your Dockerfile, it’s important to verify the version of Node.js you’re using. This ensures compatibility between your development environment and the Docker image.
node --version
This command will display the version of Node.js installed on your machine. Use this version to ensure that your Docker image is aligned with your local development environment, ensuring consistency across different environments.
Create the Dockerfile:
In the root level of your project, create a file named Dockerfile and add the following configuration:

## Dockerfile
################################
## BUILD ENVIRONMENT ###########
################################

# Use the official Node.js Alpine image (adjust based on your project's requirements)
# You can find the appropriate image on Docker Hub: https://hub.docker.com/_/node
# In this example, we're using node:20-alpine3.20
# run in termilnal commande line "node --version to get the version of your app"
FROM node:20-alpine3.20 As build

# Set the working directory inside the container
WORKDIR /usr/src/app

# Copy package.json and package-lock.json into the container
COPY package*.json package-lock.json ./

# Install dependencies using npm
RUN npm ci

# Copy the project files into the working directory
COPY ./ ./

# Build the React app for production
RUN npm run build

################################
#### PRODUCTION ENVIRONMENT ####
################################

# Use the official NGINX image for production
FROM nginx:stable-alpine as production

# copy nginx configuration in side conf.d folder
COPY --from=build /usr/src/app/nginx /etc/nginx/conf.d

# Copy the build output from the dist folder into the Nginx html directory
COPY --from=build /usr/src/app/dist /usr/share/nginx/html

# Expose port 80 to allow access to the app
EXPOSE 80

# Run Nginx in the foreground
ENTRYPOINT ["nginx", "-g", "daemon off;"]

With this Dockerfile, you can build a Docker image for your React app and deploy it using Nginx. The image will handle both the build process and the production serving, streamlining your deployment workflow.

Create a .dockerignore File:
To optimize the Docker image build process and reduce the size of your image, it’s important to exclude unnecessary files and directories. You can achieve this by creating a .dockerignore file in the root of your project. This file works similarly to a .gitignore file, specifying which files and directories should be ignored when building the Docker image.
In the root level of your project, create a file named .dockerignore and add the following content:

## .dockerignore
# Ignore node_modules directory to prevent copying unnecessary dependencies
node_modules

# Ignore local editor settings
.vscode

# Ignore Git repository files
.git

# Ignore build folder
dist
build

# Ignore ESLint, Prettier, and other configuration files that aren't needed in the final image
.eslint*
.prettier*
.editorconfig
.DS_Store

5- Build and Run Your Docker Image

After configuring your Dockerfile and .dockerignore file, you're ready to build and run your Docker image. Follow these steps:

Build the Docker Image:
This command will create a Docker image based on your Dockerfile.

## Use the following command to build your Docker image. You can name the image according to your preference; in this example, it's named deploy-vite-app-using-nginx:
docker build -t deploy-vite-app-using-nginx .

Run the Docker Container:
Start a new container from the image using the following command:

## Assigns a name to the container using flag --name "example"
docker run -d --name my-app-container -p 80:80 deploy-vite-app-using-nginx

Check Running Containers:
To verify that your container is running, use the following command:

docker ps

View Container Logs:
To view the logs for your running container, use:

docker logs my-app-container

These steps will help you build, run, and manage your Docker container effectively, ensuring that your Vite-powered React app is correctly deployed using Nginx.

6. Verifying the Deployment

To verify that your React application is up and running, follow these steps:

Open Your Web Browser:
Launch your preferred web browser (e.g., Chrome, Firefox, Safari).
Navigate to the Application:
In the address bar, type http://localhost and press Enter.
View Your Application:
You should now see your React application’s home page, confirming that the deployment was successful.

This step ensures that the application is correctly hosted and accessible on your local server.

Conclusion

Deploying a React app built with Vite on an Nginx server is a powerful way to deliver a fast, reliable web application. With Vite’s optimized build and Nginx’s robust serving capabilities, your React app is well-equipped to handle production traffic. Whether you’re serving a simple web page or a complex single-page application, this setup provides the flexibility and performance needed for modern web applications.