Skip to content
Go back

Week 5: Containerizing a React Frontend

Edit page

🐳 Docker 360 β€” Week 5 of 16 | Ship a React app in a tiny nginx container

🎯 Learning Objective

By the end of this week, you will be able to containerize any React (Vite) frontend using a multi-stage Dockerfile that builds the app with Node and serves the static output with nginx. You will also understand .dockerignore, build-time arguments for API URLs, and how to make client-side routing work inside a container. Iska matlab ye hai ke β€” after this post, docker build + docker run will give you a production-ready frontend in under 50 MB.

🎨 Visual Diagrams

Multi-stage build: what goes where

 β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
 β”‚  STAGE 1: "build"  (node:22-alpine) β”‚
 β”‚                                    β”‚
 β”‚   1. COPY package*.json            β”‚
 β”‚   2. RUN npm ci        (deps)      β”‚
 β”‚   3. COPY . .          (source)    β”‚
 β”‚   4. RUN npm run build (β†’ /app/dist)β”‚
 β”‚                                    β”‚
 β”‚   ~350 MB of tools β€” THROWN AWAY   β”‚
 β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                β”‚  COPY --from=build /app/dist
                β–Ό
 β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
 β”‚  STAGE 2: runtime (nginx:1.27-alpine)β”‚
 β”‚                                    β”‚
 β”‚   /usr/share/nginx/html  ← dist    β”‚
 β”‚   nginx serves static files on :80 β”‚
 β”‚                                    β”‚
 β”‚   Final image β‰ˆ 45 MB βœ…            β”‚
 β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

Iska matlab ye hai ke β€” the heavy Node toolchain never ships to production. Only the compiled HTML/CSS/JS travels in the final image.

Request flow: SPA routing inside nginx

 Browser
   β”‚
   β”‚  GET /dashboard   (a React Router page β€” no real file!)
   β–Ό
 β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
 β”‚  nginx container  (:8080β†’:80)β”‚
 β”‚                             β”‚
 β”‚  try_files $uri $uri/       β”‚
 β”‚       /index.html;  ◀── fallback: "file nahi mili?
 β”‚                             β”‚     index.html de do,
 β”‚                             β”‚     React Router sambhal lega"
 β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

Build context: why .dockerignore matters

 WITHOUT .dockerignore              WITH .dockerignore
 ─────────────────────              ──────────────────
 build context: 412 MB              build context: 3.1 MB
  β”œβ”€ node_modules/  (useless!)       β”œβ”€ src/
  β”œβ”€ dist/          (stale!)         β”œβ”€ public/
  β”œβ”€ .git/          (heavy!)         β”œβ”€ package*.json
  └─ src/ ...                       └─ vite.config.js

 Slower uploads, broken cache  ──▢  Fast builds, correct layer cache

🧠 Theory Deep Dive

Why multi-stage builds exist

A React app has two lives: build time (needs Node, npm, devDependencies, ~350 MB) and run time (needs only a static file server β€” nginx, ~25 MB). A single-stage image drags both lives into production: bigger images, slower deploys, larger attack surface.

Multi-stage builds solve this with multiple FROM instructions in one Dockerfile. Each FROM starts a fresh stage; you COPY --from=<stage> only the artifacts you need into the final stage. Intermediate stages are discarded from the final image.

ApproachFinal image sizeBuild tools shipped?Production-ready?
Single stage (node + serve)~400 MBYes (npm, node_modules)Meh
Multi-stage (node β†’ nginx)~45 MBNoβœ… Yes

.dockerignore β€” the unsung hero

Everything in your project folder is sent to the Docker daemon as the build context. Without .dockerignore, you ship node_modules, .git, and old dist folders into every build β€” slow and cache-breaking. Iska matlab ye hai ke β€” a good .dockerignore is free build speed.

node_modules
dist
.git
.env
*.log

ARG vs ENV β€” build-time vs run-time config

This confuses everyone, so let’s settle it:

ARGENV
Set via--build-arg at build timeENV in Dockerfile or -e at run time
Visible inBuild onlyBuild + running container
Use forAPI URLs, version numbers baked into the buildRuntime config like PORT, NODE_ENV

For a Vite React app, the API URL must be known at build time, because Vite bakes import.meta.env.VITE_API_URL into the compiled JS. That’s why we pass it as a build arg. Iska matlab ye hai ke β€” frontend env vars are frozen at docker build, not docker run. If your API URL changes, you rebuild the image.

⚠️ Vite only exposes variables prefixed with VITE_ to your app code. API_URL alone will be undefined in the browser β€” a classic gotcha.

nginx try_files and SPA routing

React Router (and friends) do client-side routing: /dashboard doesn’t exist as a file on the server. Without special config, nginx returns 404 when you refresh on that URL. The fix:

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

Translation: β€œtry the exact file, then the directory, otherwise serve index.html and let React Router figure out the route.” Iska matlab ye hai ke β€” every unknown path falls back to your app instead of a 404 page.

πŸ’» Hands-On Lab

We will scaffold a real Vite React app, containerize it with a multi-stage Dockerfile, and serve it on nginx β€” all inside Docker (no local Node needed).

Step 1 β€” Verify Docker is ready

docker --version
docker info --format '{{.ServerVersion}}'

βœ… Expected result: version numbers print with no errors.

Step 2 β€” Scaffold a Vite React app (inside a throwaway Node container)

mkdir -p ~/docker360/week5 && cd ~/docker360/week5
docker run --rm -v "$PWD":/app -w /app node:22-alpine \
  sh -c "npm create vite@latest frontend -- --template react"
cd frontend
ls

βœ… Expected result: ls shows package.json, src/, index.html, vite.config.js β€” a fresh React app, and you never installed Node locally.

Step 3 β€” Add an API URL usage to the app (so build args mean something)

Open src/App.jsx and add one line near the top of the component:

<p>API URL: {import.meta.env.VITE_API_URL || "not set"}</p>

Iska matlab ye hai ke β€” when we build with --build-arg VITE_API_URL=..., this value gets baked into the page.

Step 4 β€” Create the .dockerignore

Create frontend/.dockerignore:

node_modules
dist
.git
.env
*.log

Step 5 β€” Create the custom nginx config (SPA fallback)

Create frontend/nginx.conf:

server {
    listen 80;
    server_name _;

    root /usr/share/nginx/html;
    index index.html;

    # SPA fallback: let React Router handle unknown routes
    location / {
        try_files $uri $uri/ /index.html;
    }

    # Cache static assets aggressively
    location /assets/ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
}

Step 6 β€” Write the multi-stage Dockerfile

Create frontend/Dockerfile:

# ---------- Stage 1: build ----------
FROM node:22-alpine AS build
WORKDIR /app

# Build-time API URL (baked into the JS bundle by Vite)
ARG VITE_API_URL
ENV VITE_API_URL=$VITE_API_URL

# Install deps first β†’ better layer caching
COPY package*.json ./
RUN npm ci

COPY . .
RUN npm run build

# ---------- Stage 2: serve ----------
FROM nginx:1.27-alpine
COPY --from=build /app/dist /usr/share/nginx/html
COPY nginx.conf /etc/nginx/conf.d/default.conf
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

Notice the layer order: COPY package*.json + npm ci happens before COPY . ., so dependency installation is cached unless your dependencies change. Iska matlab ye hai ke β€” code edits rebuild in seconds instead of minutes.

Step 7 β€” Build the image with a build arg

docker build --build-arg VITE_API_URL=https://api.example.com -t react-frontend:1.0 .

βœ… Expected result: final lines show writing image sha256:... and naming to docker.io/library/react-frontend:1.0.

Step 8 β€” Compare the size (the multi-stage payoff)

docker images react-frontend --format '{{.Repository}}:{{.Tag}}  {{.Size}}'

βœ… Expected result: roughly 40–60 MB. A single-stage Node image of the same app would be 400+ MB.

Step 9 β€” Run it and test

docker run -d --name web -p 8080:80 react-frontend:1.0
curl -s http://localhost:8080 | grep -o "API URL: [^<]*"

βœ… Expected result: API URL: https://api.example.com β€” the build arg made it into the bundle.

Step 10 β€” Prove the SPA fallback works

# A route that exists only in React Router (no real file):
curl -s -o /dev/null -w "%{http_code}\n" http://localhost:8080/dashboard
curl -s http://localhost:8080/dashboard | grep -o "<title>[^<]*</title>"

βœ… Expected result: HTTP 200 (not 404) and the app’s <title> β€” nginx served index.html as the fallback.

Step 11 β€” Clean up

docker stop web && docker rm web

βœ… Checkpoint

Q1: Why use a multi-stage Dockerfile for a React app instead of serving from the Node image? A1: The Node stage is only needed to compile the app. The final nginx stage contains just static files (~45 MB), so the image is smaller, faster to deploy, and has a smaller attack surface.

Q2: What’s the difference between ARG and ENV in a Dockerfile? A2: ARG is set with --build-arg and exists only during the build; ENV persists into the running container and can be overridden with -e at run time.

Q3: Why does refreshing on /dashboard give a 404 without the nginx try_files fix? A3: Because /dashboard is a client-side React Router route β€” no such file exists on the server. try_files $uri $uri/ /index.html falls back to index.html so the router can render the page.

Q4: Your Vite app shows VITE_API_URL as undefined in the browser even though you passed -e VITE_API_URL=... to docker run. Why? A4: Vite bakes env vars into the JS bundle at build time. You must pass it as --build-arg during docker build; runtime -e flags can’t change already-compiled static files.

πŸ”œ Next Week

Week 6: we flip to the backend β€” containerizing a Node.js API the production way, with non-root users, graceful shutdowns, and health checks.


Edit page
Share this post on:

Previous Post
Week 6: Containerizing a Node.js Backend
Next Post
Week 4: Orchestration Fundamentals