Alpine didn't break your Vite build. A missing optional dependency did.
The advice is everywhere in Docker threads: if a Node build fails on Alpine, switch to Debian.
I tested that claim against a real Vite 7 / React 19 / Tailwind 4 app. Alpine was innocent.
The test
Same source, four setups, one question: does the build produce a working bundle?
| Setup | node_modules/@rollup | Build |
|---|---|---|
node:22-alpine, npm install | rollup-linux-x64-musl | ✅ passes |
node:22-alpine, npm ci with a lockfile generated on Debian | rollup-linux-x64-gnu, rollup-linux-x64-musl | ✅ passes |
node:22-alpine, npm install --omit=optional | (empty) | ❌ fails immediately |
node:22-bookworm-slim, npm ci | rollup-linux-x64-gnu, rollup-linux-x64-musl | ✅ passes |
A clean install on musl builds a React app without complaint. So the base image is not the variable. The variable is whether Rollup's native parser got installed.
Why the parser is a package
Rollup 4 parses JavaScript with a native binary, not with JavaScript. That binary ships as a platform-specific optional dependency:
-
@rollup/rollup-linux-x64-gnu— glibc (Debian, Ubuntu,node:22-slim) -
@rollup/rollup-linux-x64-musl— musl (Alpine)
The loader picks by libc at runtime, and there is no silent fallback: if the package is missing, Rollup stops and tells you which one it wanted.
The error is more useful than the advice
Here is what a missing package actually looks like:
Error: Cannot find module @rollup/rollup-linux-x64-musl. npm has a bug related to optional dependencies (https://github.com/npm/cli/issues/4828). Please try `npm i` again after removing both package-lock.json and node_modules directory. That message names the package, the libc, and the fix. It does not mention Alpine, because Alpine is not the problem.
Check it in ten seconds
Inside the failing image:
ls node_modules/@rollup Expected on Alpine:
rollup rollup-linux-x64-musl If @rollup contains only rollup, the native parser is missing and every build is running on borrowed time. Confirm which libc you're on:
node -p "process.report.getReport().header.glibcVersionRuntime" # undefined → musl (Alpine) # '2.36' → glibc (Debian) Three ways the package goes missing
1. Optional dependencies were skipped. npm ci --omit=optional, npm install --no-optional, or a CI policy that strips optional packages removes the native binding along with everything else. This is the only one of the three that reliably reproduces today, and it fails loudly.
2. node_modules was copied from the host. COPY . . after running npm install on your laptop ships a macOS or glibc node_modules into a musl image. Fix: install inside the image and put node_modules in .dockerignore. This is the most common real-world cause and the one no base-image change will fix.
3. The install and the image disagree. A lockfile or cache produced on another platform — or a lockfile that predates an optional dependency — can leave you with the wrong set. Rollup's own error message recommends the brute-force fix: remove node_modules and the lockfile, then install again inside the image.
The fix, in order of preference
Install in the image, from a lockfile:
COPY package.json package-lock.json ./ RUN npm ci --no-audit --no-fund If a policy forbids optional dependencies, install the platform package explicitly so it cannot be skipped:
npm i -D @rollup/rollup-linux-x64-musl Pin it to the same version as rollup, and remember it is arch- and libc-specific: linux-arm64-musl if you build on Apple Silicon runners targeting Alpine, linux-x64-gnu for Debian.
Then verify instead of hoping. Add a line to the build that fails with a readable message:
RUN node -e "require.resolve('@rollup/rollup-linux-x64-musl')" A missing parser then breaks on the line that caused it, not inside a bundler stack trace.
When to switch to Debian anyway
The advice isn't wrong every time. It's wrong as a first move. Switch the build stage when:
- a tool ships no musl build at all;
- a native module is compiled at install time and its prebuilds assume glibc;
- you don't control the install (vendored lockfile, older npm with the optional-dependency bug).
The cost is one layer in a stage nobody runs. Measured on this project: node:22-alpine is 239 MB, node:22-bookworm-slim is 329 MB — 90 MB that never reaches production, because the runtime stage is a separate image.
What the Dockerfile looks like
# ---- build stage ----------------------------------------------------------- # Debian slim for the build stage because Rollup's native parser is a per-libc # optional dependency (@rollup/rollup-linux-x64-gnu vs -musl). Alpine builds work # when the install includes it; a copied node_modules or an --omit=optional # install is what leaves Rollup without a parser and stops the build. FROM node:22-bookworm-slim AS build WORKDIR /app COPY package.json package-lock.json ./ RUN npm ci --no-audit --no-fund COPY . . RUN npm run build # ---- runtime stage --------------------------------------------------------- # No Node, no libc concerns: static files behind nginx. FROM nginx:1.27-alpine AS runtime COPY docker/nginx.conf /etc/nginx/conf.d/default.conf RUN rm -rf /usr/share/nginx/html/* COPY --from=build /app/dist /usr/share/nginx/html EXPOSE 80 HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \ CMD wget -qO- http://127.0.0.1/healthz >/dev/null 2>&1 || exit 1 CMD ["nginx", "-g", "daemon off;"] The libc only matters where native binaries run. Bundling happens in a stage that gets thrown away; serving static files needs no compatibility layer at all, so the runtime stays on Alpine and stays small.
The rule
Pin the platform to the binary, not to the image size — and when a build fails in a container, read what the tool says it's missing before you change the base image.
ls node_modules/@rollup takes ten seconds. Rewriting a Dockerfile around a wrong diagnosis costs an afternoon, and leaves a comment in the repo that misleads the next person.