DEV Community

Miii
Miii

Posted on

Alpine didn't break your Vite build. A missing optional dependency did.

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.
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Expected on Alpine:

rollup
rollup-linux-x64-musl
Enter fullscreen mode Exit fullscreen mode

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)
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

If a policy forbids optional dependencies, install the platform package explicitly so it cannot be skipped:

npm i -D @rollup/rollup-linux-x64-musl
Enter fullscreen mode Exit fullscreen mode

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')"
Enter fullscreen mode Exit fullscreen mode

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;"]
Enter fullscreen mode Exit fullscreen mode

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.

Top comments (0)