docker images<\/code> out of habit and stared at the number for a good ten seconds. The image was 1.1 GB, for an app whose actual code was only a few hundred kilobytes.<\/p>\nIt still worked, so I let it slide. Then the deploys started getting slower, our registry storage bill crept up, and a security scan flagged a pile of build tools that had no business being in a running container. That 1.1 GB was the problem. A multi-stage Docker build is how we got it down to about 150 MB without changing a single line of application code.<\/p>\n
Why Your Node.js Image Gets So Big<\/h2>\n
When you build a Node app inside Docker, you need a lot of stuff at build time<\/em>:<\/p>\n\n- The full
node_modules<\/code> folder, including dev dependencies like TypeScript, webpack, Babel, and testing libraries<\/li>\n- Your raw source code<\/li>\n
- Compilers and build tooling<\/li>\n<\/ul>\n
But when the app is actually running<\/em>, it needs almost none of that. It needs the compiled output and the production dependencies. That is it.<\/p>\nWith a plain, single-stage Dockerfile, everything you pulled in to build the app stays inside the final image. All that tooling rides along to production as dead weight: bigger images, slower deploys, and a larger surface for something to go wrong.<\/p>\n
What Is a Multi-Stage Docker Build?<\/h2>\n
A multi-stage build lets you use more than one FROM<\/code> statement in a single Dockerfile. Each FROM<\/code> starts a fresh stage with its own base image. Do the heavy lifting in one stage, then copy just the finished output into a clean final stage and throw the rest away.<\/p>\nThink of it like a kitchen. Cooking needs pans, a board, and gas, and it leaves a pile of scraps. But you serve the customer the plate, not the whole kitchen. The build stage is the messy kitchen; the final stage is the plate.<\/p>\n
<\/p>\n
The Single-Stage Dockerfile We Started With<\/h2>\n
This is roughly what our original file looked like:<\/p>\n
FROM node:20\r\nWORKDIR \/app\r\nCOPY package*.json .\/\r\nRUN npm install\r\nCOPY . .\r\nRUN npm run build\r\nCMD [\"node\", \"dist\/index.js\"]<\/pre>\nIt works, but the full node:20<\/code> base image, every dev dependency, and all the source code get baked into the image you ship. Nothing is thrown away.<\/p>\nRewriting It as a Multi-Stage Build<\/h2>\n
Here is the same app, restructured into two stages:<\/p>\n
# ---- Stage 1: build ----\r\nFROM node:20 AS builder\r\nWORKDIR \/app\r\nCOPY package*.json .\/\r\nRUN npm install\r\nCOPY . .\r\nRUN npm run build\r\n\r\n# ---- Stage 2: runtime ----\r\nFROM node:20-alpine\r\nWORKDIR \/app\r\nENV NODE_ENV=production\r\nCOPY package*.json .\/\r\nRUN npm install --omit=dev\r\nCOPY --from=builder \/app\/dist .\/dist\r\nCMD [\"node\", \"dist\/index.js\"]<\/pre>\nTwo things changed. The first stage is named builder<\/code> and does all the installing and compiling. The second stage starts from node:20-alpine<\/code>, a much smaller base. It installs only production dependencies and pulls in the compiled dist<\/code> folder from the first stage.<\/p>\nWhat That COPY --from<\/code> Line Actually Does<\/h3>\nCOPY --from=builder \/app\/dist .\/dist<\/code> is the one line doing the real work here. It reaches back into the builder<\/code> stage and copies out just the compiled output. Everything else from that stage (the dev dependencies, the source, the build tools) never makes it into the final image.<\/p>\nDocker only ships the last stage; earlier stages are just a source to copy from, then discarded. All that build-time weight never travels to production.<\/p>\n
![\"multi-stage](\"https:\/\/2thenew.xyz\/blog\/wp-ttn-blog\/uploads\/2026\/08\/docker-stages.png\")
<\/p>\n
The Results: An 85% Smaller Docker Image<\/h2>\n
Same app, same behaviour, very different image. Running docker images<\/code> after each build tells the whole story (trimmed to the columns that matter):<\/p>\nREPOSITORY TAG SIZE\r\nmy-api single-stage 1.1GB\r\nmy-api multi-stage 150MB<\/pre>\n![\"Docker](\"https:\/\/2thenew.xyz\/blog\/wp-ttn-blog\/uploads\/2026\/08\/docker-size.png\")
<\/p>\n
That is roughly an 85% cut. Your exact numbers depend on your app and base image, but the direction is always the same: smaller images push and pull faster, so deploys and autoscaling stop dragging. You also stop paying to store a gigabyte of build tools you never run, and your security scanner has less to complain about.<\/p>\n
Do Not Forget a .dockerignore File<\/h2>\n
A multi-stage build only helps if you are not quietly copying junk into the build context in the first place. A .dockerignore<\/code> file keeps local clutter out of every COPY<\/code>:<\/p>\nnode_modules\r\nnpm-debug.log\r\n.git\r\n.env\r\ndist\r\nDockerfile\r\n<\/pre>\nWithout this, a COPY . .<\/code> can drag in your local node_modules<\/code> or a stray .env<\/code> file, which slows the build and, in the case of secrets, creates a real security problem. Treat it like .gitignore<\/code> for your image.<\/p>\nCommon Mistakes to Avoid<\/h2>\n
A few of these bit us (or people whose PRs I have reviewed) more than once:<\/p>\n
\n- Copying
node_modules<\/code> from the host.<\/strong> Let Docker install deps inside the image; host copies can pull in the wrong platform binaries and break at runtime.<\/li>\n- Wrong layer order.<\/strong> A
COPY . .<\/code> before installing means every code change busts that layer’s build cache and forces a full reinstall. Copy package*.json<\/code> and install first.<\/li>\n- Leaving dev dependencies in the final stage.<\/strong> Use
npm install --omit=dev<\/code> (or npm ci --omit=dev<\/code>, which needs a committed package-lock.json<\/code>) in the runtime stage so testing and build-only packages never ship.<\/li>\n- Forgetting to copy runtime assets.<\/strong> If your app needs more than the compiled code (templates, migrations, static files), remember to
COPY --from=builder<\/code> those too, or the container will start and then fall over.<\/li>\n<\/ul>\nWhen You Might Not Need This<\/h2>\n
Multi-stage builds are worth it for almost any real service, but they are not a law. A tiny script with no build step and a handful of dependencies is fine on a single well-trimmed stage. The moment you have a compile step, dev-only tooling, or an image you deploy often, though, the split pays for itself.<\/p>\n
Conclusion<\/h2>\n
Multi-stage builds gave us a smaller, faster, safer image for the price of restructuring one file. No code changes, no new tools, no separate build scripts, just a clean separation between how the app is built and how it runs.<\/p>\n
Pull up one of your own images, run docker images<\/code>, and see the number. Then split the Dockerfile into a build stage and a runtime stage and measure the difference. For most Node images, it is the easiest win on the table.<\/p>\nFound this useful? Leave a comment with your before-and-after image sizes.<\/p>\n","protected":false},"excerpt":{"rendered":"
Introduction The first time I shipped a Node.js service to production, I ran docker images out of habit and stared at the number for a good ten seconds. The image was 1.1 GB, for an app whose actual code was only a few hundred kilobytes. It still worked, so I let it slide. Then the […]<\/p>\n","protected":false},"author":1714,"featured_media":0,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"iawp_total_views":17,"footnotes":""},"categories":[5876],"tags":[1891,1892,1883,2558,8808,1177],"class_list":["post-81214","post","type-post","status-publish","format-standard","hentry","category-js","tag-containers","tag-devops","tag-docker","tag-dockerfile","tag-multistage","tag-nodejs-2"],"aioseo_notices":[],"aioseo_head":"\n\t\t\n\t\n\t\n\t\n\t\n\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t