π³ 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.
| Approach | Final image size | Build tools shipped? | Production-ready? |
|---|---|---|---|
Single stage (node + serve) | ~400 MB | Yes (npm, node_modules) | Meh |
| Multi-stage (node β nginx) | ~45 MB | No | β 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:
ARG | ENV | |
|---|---|---|
| Set via | --build-arg at build time | ENV in Dockerfile or -e at run time |
| Visible in | Build only | Build + running container |
| Use for | API URLs, version numbers baked into the build | Runtime 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_URLalone will beundefinedin 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.