3.3.2.2 Node Runtime Images

Node runtime images provide the Node.js JavaScript runtime pre-installed on top of an operating system base, serving as the standard foundation for containerizing applications written for Node.js, including its package manager for installing project dependencies.

Basic Node Application Containerization

A typical Node application's Dockerfile installs dependencies declared in package.json, copies the application source, and starts the application using Node directly.

FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
CMD ["node", "server.js"]

Separating Dependency Installation From Source Copying

Copying dependency manifests and installing them before copying the rest of the application source takes advantage of layer caching, so that a rebuild after only a source code change does not need to reinstall dependencies.

docker build -t myapp:1.0 .
echo "// updated" >> server.js
docker build -t myapp:1.1 .

The second build reuses the cached dependency installation layer entirely, since package*.json did not change.

Production Dependency Installation

For production images, installing only production dependencies, omitting development tools like test runners or bundlers, keeps the final image smaller.

RUN npm install --omit=dev

Multi-Stage Builds for Compiled Frontend Assets

Applications that need a build step (bundling, transpiling) commonly use a multi-stage build, performing the build in a fuller Node image and copying only the compiled output into a smaller final image.

FROM node:20 AS build
WORKDIR /app
COPY . .
RUN npm install && npm run build

FROM node:20-alpine
WORKDIR /app
COPY --from=build /app/dist ./dist
COPY package*.json ./
RUN npm install --omit=dev
CMD ["node", "dist/server.js"]

Choosing Between Node Image Variants

Node images are available in full, slim, and Alpine-based variants, with the same general size-versus-compatibility tradeoffs that apply to other language runtime base images, plus the consideration of whether any native Node modules require glibc compatibility.

docker images node

Why Node Runtime Images Matter

Official Node runtime images standardize containerizing JavaScript applications across the ecosystem, providing a consistent, well-maintained foundation that handles runtime installation so a project's own Dockerfile can focus entirely on its specific dependencies and build process.