An essential tenet of modern DevOps is creating small, efficient Docker images. For a React/Vue application, a typical non-optimized image can balloon to hundreds of megabytes. The best dependency is no dependency. The best dependency is no dependency. Press enter or click to view image in full size By implementing Multi-Stage Builds and other key techniques, you can often achieve a 10x reduction in size, significantly improving deployment speed, reducing registry storage, and shrinking your attack surface. This guide provides a step-by-step approach to dramatically reduce your React / Vue application’s Docker image size, including how to embed your software version for runtime identification. The Power of Multi-Stage Builds: From Bloat to Minimal A single-stage Dockerfile for a React app requires the entire Node.js environment, dependencies, and build tools in the final image, even though they’re only needed for the build process. The solution is the Multi-Stage Build pattern. It separates the heavy build environment from the minimal runtime environment. By using a multi-stage approach, we only include the tiny Built Static Files and a minimal web server in the final image. Built Static Files Optimized Multi-Stage Dockerfile We will use two stages: Builder Stage: Uses a larger node:lts-alpine image to install dependencies and run npm run build (you can use yarn also). This stage is discarded after the build. Builder Stage: node:lts-alpine npm run build Final Stage: Uses the ultra-minimal nginx:alpine image to serve the static files copied from the builder stage. Final Stage: nginx:alpine The nginx:alpine image is typically only ~20 MB — a massive reduction from a Node.js-based image! nginx:alpine ~20 MB Step-by-Step Optimization Guide Step 1: Initialize the DockerfileCreate a file named Dockerfile in the root of your React project. Step 1: Initialize the Dockerfile Dockerfile Step 2: The builder StageThis stage is responsible for all the heavy lifting — installing Node, fetching dependencies, and compiling the React application. Step 2: The builder Stage # Stage 1: The Builder Stage
FROM node:lts-alpine AS builder

# Set the working directory inside the container
WORKDIR /app

# Copy package.json and lock file first to leverage Docker's build cache
# Only run npm install if package files change
COPY package*.json ./
RUN npm install

# Copy all other source files
COPY . .

# Run the build command - typically outputs to 'build' folder for Create-React-App
RUN npm run build # Stage 1: The Builder Stage
FROM node:lts-alpine AS builder

# Set the working directory inside the container
WORKDIR /app

# Copy package.json and lock file first to leverage Docker's build cache
# Only run npm install if package files change
COPY package*.json ./
RUN npm install

# Copy all other source files
COPY . .

# Run the build command - typically outputs to 'build' folder for Create-React-App
RUN npm run build Optimization Notes for this Stage: Optimization Notes for this Stage: Minimal Base Image: We use node:lts-alpine instead of a full node:lts image. Alpine is a very small, security-focused Linux distribution. Minimal Base Image: node:lts-alpine node:lts Build Cache Leverage: Copying package*.json and running npm install before copying the rest of the source files ensures that Docker only re-runs the long npm install step if your dependencies change, not every time you change a source file. Build Cache Leverage: package*.json npm install Step 3: The final (Production) StageThis stage uses a lean, production-ready web server to host the built assets. Step 3: The final (Production) Stage # Stage 2: The Final Production Stage
FROM nginx:alpine

# Copy the build output from the 'builder' stage to the Nginx public directory
# The 'build' directory is where 'npm run build' typically puts the static assets.
COPY --from=builder /app/build /usr/share/nginx/html

# Expose the port Nginx runs on
EXPOSE 80

# Command to start Nginx, serving the content
CMD ["nginx", "-g", "daemon off;"] # Stage 2: The Final Production Stage
FROM nginx:alpine

# Copy the build output from the 'builder' stage to the Nginx public directory
# The 'build' directory is where 'npm run build' typically puts the static assets.
COPY --from=builder /app/build /usr/share/nginx/html

# Expose the port Nginx runs on
EXPOSE 80

# Command to start Nginx, serving the content
CMD ["nginx", "-g", "daemon off;"] Key Optimization: Key Optimization: FROM nginx:alpine: Using an ultra-minimal image (around 20 MB) as the final layer. FROM nginx:alpine: 20 MB COPY — from=builder: This is the magic of multi-stage builds. We only copy the small, compiled static files (/app/build) from the preceding stage, discarding the entire Node.js, node_modules, and build tool environment. COPY — from=builder: Highlighting the Current Software Version (DevOps Insight) In DevOps, knowing the exact software version running in production is critical for debugging, rollbacks, and tracking. We’ll use a Build Argument (ARG) to inject the version (e.g., from your CI/CD pipeline, Git tag, or Merge Request (MR) ID) into the image at build time, and then surface it in your application code. Step 3.1: Pass the Version via Docker ARGModify the builder stage to accept a BUILD_VERSION argument: Step 3.1: Pass the Version via Docker ARG BUILD_VERSION # ... (Previous code)
# Stage 1: The Builder Stage
FROM node:lts-alpine AS builder
# Define a build argument for the software version
ARG BUILD_VERSION=unknown 

WORKDIR /app

# ... (rest of Stage 1 code)

# Build the app, passing the version as a variable to React's build process
# REACT_APP_VERSION is a standard pattern for exposing ENV vars to a React build
RUN npm run build # ... (Previous code)
# Stage 1: The Builder Stage
FROM node:lts-alpine AS builder
# Define a build argument for the software version
ARG BUILD_VERSION=unknown 

WORKDIR /app

# ... (rest of Stage 1 code)

# Build the app, passing the version as a variable to React's build process
# REACT_APP_VERSION is a standard pattern for exposing ENV vars to a React build
RUN npm run build When building, you will pass the version: # Example using a CI variable for the Merge Request ID
MR_ID="mr-12345"
docker build --build-arg BUILD_VERSION=${MR_ID} -t my-react-app:${MR_ID} . # Example using a CI variable for the Merge Request ID
MR_ID="mr-12345"
docker build --build-arg BUILD_VERSION=${MR_ID} -t my-react-app:${MR_ID} . **Step 3.2: Access the Version in React (App Build/MR Code)**You need to configure your React build process (e.g., in your project’s .env file, webpack config, or a special script) to consume the Docker ARG value and embed it into the application’s environment variables. .env For a standard Create-React-App setup, you usually pass environment variables to the npm run build command. Since we can’t directly use an ARG as an ENV in a single command, the common and cleanest pattern is to use a simple script or directly embed the variable during the RUN instruction. npm run build The Crucial Dockerfile Code (Combined RUN for npm run build): The Crucial Dockerfile Code (Combined RUN for npm run build): To ensure the build argument is passed as an environment variable visible to the React build script: # Stage 1: The Builder Stage
FROM node:lts-alpine AS builder
# Define a build argument for the software version
ARG BUILD_VERSION=unknown 

# ... (other setup)

# **HIGHLIGHTED APP BUILD/MR CODE INJECTION**
# Pass the BUILD_VERSION ARG as a REACT_APP_VERSION ENV to the build process
RUN REACT_APP_VERSION=${BUILD_VERSION} npm run build 
# Your app code (e.g., package.json scripts) should ensure this variable is embedded. # Stage 1: The Builder Stage
FROM node:lts-alpine AS builder
# Define a build argument for the software version
ARG BUILD_VERSION=unknown 

# ... (other setup)

# **HIGHLIGHTED APP BUILD/MR CODE INJECTION**
# Pass the BUILD_VERSION ARG as a REACT_APP_VERSION ENV to the build process
RUN REACT_APP_VERSION=${BUILD_VERSION} npm run build 
# Your app code (e.g., package.json scripts) should ensure this variable is embedded. The Corresponding React Application Code (e.g., in App.js or a Footer component): The Corresponding React Application Code (e.g., in App.js or a Footer component): The React app’s code uses the standard way of accessing build-time environment variables: import React from 'react';

function Footer() {
  // **HIGHLIGHTED APP BUILD/MR CODE**
  const version = process.env.REACT_APP_VERSION || 'local-dev';
  
  return (
    <footer>
      Running Software Version: **{version}** 🚀
    </footer>
  );
}

export default Footer; import React from 'react';

function Footer() {
  // **HIGHLIGHTED APP BUILD/MR CODE**
  const version = process.env.REACT_APP_VERSION || 'local-dev';
  
  return (
    <footer>
      Running Software Version: **{version}** 🚀
    </footer>
  );
}

export default Footer; This ensures that the Merge Request ID, Git SHA, or any other critical version identifier is baked directly into the static assets, easily visible to developers or support teams. Final Optimized Dockerfile or Fast Deployment Is a Small Deployment. Here is the complete, size-optimized, multi-stage Dockerfile with version injection: # --------------------------------------------------------------------------------
# STAGE 1: BUILDER
# Uses a lean Node image to install dependencies and compile the React app
# --------------------------------------------------------------------------------
FROM node:lts-alpine AS builder

# Define a build argument for the version (default to 'unknown' if not provided)
ARG BUILD_VERSION=unknown

WORKDIR /app

# Copy package files first to enable caching of npm install
COPY package*.json ./
RUN npm install

# Copy application source code
COPY . .

# Pass the BUILD_VERSION as an environment variable during the build
# This value will be baked into the static assets (e.g., accessible via process.env.REACT_APP_VERSION)
# **HIGHLIGHTED APP BUILD/MR CODE**
RUN REACT_APP_VERSION=${BUILD_VERSION} npm run build

# --------------------------------------------------------------------------------
# STAGE 2: FINAL PRODUCTION IMAGE
# Uses a minimal Nginx image to serve the compiled static files
# --------------------------------------------------------------------------------
FROM nginx:alpine

# Copy the built React application files from the 'builder' stage
# This step discards the entire Node.js environment, reducing size by >90%
COPY --from=builder /app/build /usr/share/nginx/html

# Expose the standard HTTP port
EXPOSE 80

# Start Nginx
CMD ["nginx", "-g", "daemon off;"] # --------------------------------------------------------------------------------
# STAGE 1: BUILDER
# Uses a lean Node image to install dependencies and compile the React app
# --------------------------------------------------------------------------------
FROM node:lts-alpine AS builder

# Define a build argument for the version (default to 'unknown' if not provided)
ARG BUILD_VERSION=unknown

WORKDIR /app

# Copy package files first to enable caching of npm install
COPY package*.json ./
RUN npm install

# Copy application source code
COPY . .

# Pass the BUILD_VERSION as an environment variable during the build
# This value will be baked into the static assets (e.g., accessible via process.env.REACT_APP_VERSION)
# **HIGHLIGHTED APP BUILD/MR CODE**
RUN REACT_APP_VERSION=${BUILD_VERSION} npm run build

# --------------------------------------------------------------------------------
# STAGE 2: FINAL PRODUCTION IMAGE
# Uses a minimal Nginx image to serve the compiled static files
# --------------------------------------------------------------------------------
FROM nginx:alpine

# Copy the built React application files from the 'builder' stage
# This step discards the entire Node.js environment, reducing size by >90%
COPY --from=builder /app/build /usr/share/nginx/html

# Expose the standard HTTP port
EXPOSE 80

# Start Nginx
CMD ["nginx", "-g", "daemon off;"] By following this approach, you move from a massive, single-stage image (often 1 GB+) to a lean, final image powered by Nginx Alpine (typically < 50 MB) — easily achieving our 10x size reduction goal. 1 GB+ 50 MB 10x size reduction goal Conclusion: Ship Smart, Not Heavy We’ve covered a lot of ground, from minimal base images to the genius of multi-stage builds. The ultimate takeaway is this: in the world of containers, less is more, and every megabyte counts. less is more By adopting the principles discussed — choosing an Alpine pencil case over a Debian suitcase, doing your cleanup in one layer, and using a .dockerignore file as your image’s velvet rope — you’re not just saving disk space; you’re buying back precious deployment time. You’re giving your CI/CD pipeline a fresh pair of running shoes. Alpine .dockerignore Remember the DevOps mantra: “You build it, you run it.” A lean image is a reliable image, and reliability is the cornerstone of great operations. The effort you put in today to optimize your Dockerfile is a payment against future technical debt. “You build it, you run it.” Dockerfile This journey of continuous improvement is not a destination, but a never-ending process. Let’s Keep the Conversation Flowing This article is just the tip of the iceberg. The best optimization is the one that fits your specific stack. Got a tough image you just slimmed down? I’d love to hear your “honey, I shrunk the Docker” success story. Don’t let this discussion be “out of sight, out of mind.” Feel free to reach out via LinkedIn or X.Com Happy Containerizing!

Keep

Shrink Your React Docker Image by 90% with Multi-Stage Builds

About Author

Comments

TOPICS

THIS ARTICLE WAS FEATURED IN

Related Stories

Untitled Story

Autonomous Agents at Scale: Lessons from Redis + Symfony Scheduler

Using Smart Home Analytics to Improve Living Experiences and Sustainability

Your AI Agent Is Too Slow—Here’s How to Fix It

Automation of ALT Text Generation for Images Using the OpenAI API

The Noonification: How to Deal With Flapping or Broken Tests (11/29/2023)

Autonomous Agents at Scale: Lessons from Redis + Symfony Scheduler

Using Smart Home Analytics to Improve Living Experiences and Sustainability

Your AI Agent Is Too Slow—Here’s How to Fix It

Automation of ALT Text Generation for Images Using the OpenAI API

The Noonification: How to Deal With Flapping or Broken Tests (11/29/2023)

Light-Mode

Classic

Newspaper

Dark-Mode

Neon Noir

Minty

HN StartUps