React guide · 6/6

Build and Deployment

A React app built with Vite compiles down to static HTML, JavaScript and CSS files. That means you can serve it from static hosting, a CDN or a web server such as nginx without running Node.js in production. This chapter covers the production build, hosting configuration and container deployment.

Production build

npm run build     # type-check with tsc -b, then vite build
npm run preview   # serve dist locally at http://localhost:4173

The build writes a dist/ folder. Code is minified, unused code is removed, and file names under dist/assets/ include a hash derived from their contents.

dist/
├── index.html
├── vite.svg
└── assets/
    ├── index-B1c2D3e4.js
    └── index-F5g6H7i8.css

npm run preview is only for checking the build output; it is not meant to be a production server. Before deploying, use it to confirm the app behaves correctly without the development-only StrictMode double invocation.

Per-environment settings and sub-paths

Builds use the values from .env.production, and --mode selects a different env file. If the app is not served from the domain root, for example GitHub Pages at https://user.github.io/repo/, set base so asset URLs are generated correctly.

# build using .env.staging
npx vite build --mode staging

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

export default defineConfig({
  plugins: [react()],
  base: "/my-app/",
});

Environment variables starting with VITE_ end up as plain strings in the bundle, readable by anyone. Keep secret keys out of the frontend and handle them in a backend or serverless function.

SPA routing and fallbacks

With a client-side router such as React Router, opening or refreshing a URL like /users/42 asks the server for a file that does not exist, and it responds with 404. Configure your host to return index.html for every path that does not match a static file.

On Netlify, a public/_redirects file is copied into the build output as-is:

/*    /index.html   200

On Vercel, add a rewrite rule to vercel.json at the project root:

{
  "rewrites": [{ "source": "/(.*)", "destination": "/index.html" }]
}

In nginx, try_files does the same job. Hashed files in assets/ change name whenever their content changes, so they can be cached for a long time, while index.html should not be cached so new deployments show up immediately.

server {
  listen 80;
  root /usr/share/nginx/html;
  index index.html;

  location / {
    try_files $uri $uri/ /index.html;
    add_header Cache-Control "no-cache";
  }

  location /assets/ {
    add_header Cache-Control "public, max-age=31536000, immutable";
  }
}

Deploying with Docker

A multi-stage build compiles the app with Node.js and ships only the output in a small nginx image. Save the nginx configuration above as nginx.conf so it is copied in as well.

FROM node:lts-alpine AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM nginx:alpine
COPY nginx.conf /etc/nginx/conf.d/default.conf
COPY --from=build /app/dist /usr/share/nginx/html
EXPOSE 80

docker build -t my-app .
docker run --rm -p 8080:80 my-app

Listing node_modules and dist in .dockerignore keeps the build context small and the build fast.

Pre-deployment checklist

Make npm run lint and the tests (npx vitest run, npx playwright test) pass in CI.
Use npm run preview to check sub-paths, page refreshes and image URLs.
If the bundle is large, split code per screen with React.lazy and dynamic import().
When server rendering or SEO becomes important, consider moving to a framework such as Next.js.

Summary

npm run build produces static files in dist/, and npm run preview lets you check them.
Set base for sub-path deployments and an index.html fallback for client-side routing.
Cache hashed assets for a long time and index.html not at all.
A multi-stage Docker build packages the app in an nginx image you can run anywhere.

Official documentation

Questions about this chapter?