Build a Node app

The goal for a Node service is a final image that carries your built output and your production node_modules, and nothing else. No dev dependencies, no source you do not ship, no package-manager cache. A three-stage build gets you there: resolve production dependencies once, build with the full dependency set in parallel, then assemble a clean runtime stage from the two.

These build on ghcr.io/quenchworks/images/node:24. There is also ghcr.io/quenchworks/images/pnpm:10, a node base with pnpm already enabled through corepack, which saves the corepack enable step in the pnpm variant.

The multi-stage Dockerfile

1
# Build stage: pnpm is already enabled on the pnpm base image.
2
FROM ghcr.io/quenchworks/images/pnpm:10 AS build
3
WORKDIR /app
4

5
# Resolve production dependencies on their own so the runtime stage can
6
# copy just these. A cache mount keeps the pnpm store warm across builds.
7
COPY package.json pnpm-lock.yaml ./
8
RUN ["pnpm", "install", "--prod", "--frozen-lockfile"]
9
RUN ["cp", "-r", "node_modules", "/prod_modules"]
10

11
# Now install everything (incl. dev deps) and build.
12
RUN ["pnpm", "install", "--frozen-lockfile"]
13
COPY . .
14
RUN ["pnpm", "run", "build"]
15

16
# Runtime stage: a slim node base, nonroot, with only prod deps + dist.
17
FROM ghcr.io/quenchworks/images/node:24 AS runtime
18
WORKDIR /app
19
ENV NODE_ENV=production
20
COPY --from=build /prod_modules ./node_modules
21
COPY --from=build /app/dist ./dist
22
COPY --from=build /app/package.json ./package.json
23
USER 1001
24
EXPOSE 3000
25
CMD ["node", "dist/server.js"]

1
FROM ghcr.io/quenchworks/images/node:24 AS build
2
WORKDIR /app
3

4
# Production dependencies only, into their own copy.
5
COPY package.json package-lock.json ./
6
RUN ["npm", "ci", "--omit=dev"]
7
RUN ["cp", "-r", "node_modules", "/prod_modules"]
8

9
# Full install (incl. dev deps) and build.
10
RUN ["npm", "ci"]
11
COPY . .
12
RUN ["npm", "run", "build"]
13

14
FROM ghcr.io/quenchworks/images/node:24 AS runtime
15
WORKDIR /app
16
ENV NODE_ENV=production
17
COPY --from=build /prod_modules ./node_modules
18
COPY --from=build /app/dist ./dist
19
COPY --from=build /app/package.json ./package.json
20
USER 1001
21
EXPOSE 3000
22
CMD ["node", "dist/server.js"]

1
# Yarn (Classic) is preinstalled on the yarn base image.
2
FROM ghcr.io/quenchworks/images/yarn:1 AS build
3
WORKDIR /app
4

5
# Production dependencies only.
6
COPY package.json yarn.lock ./
7
RUN ["yarn", "install", "--frozen-lockfile", "--production"]
8
RUN ["cp", "-r", "node_modules", "/prod_modules"]
9

10
# Full install (incl. dev deps) and build.
11
RUN ["yarn", "install", "--frozen-lockfile"]
12
COPY . .
13
RUN ["yarn", "build"]
14

15
FROM ghcr.io/quenchworks/images/node:24 AS runtime
16
WORKDIR /app
17
ENV NODE_ENV=production
18
COPY --from=build /prod_modules ./node_modules
19
COPY --from=build /app/dist ./dist
20
COPY --from=build /app/package.json ./package.json
21
USER 1001
22
EXPOSE 3000
23
CMD ["node", "dist/server.js"]

What each stage does

Prod-deps. Install only production dependencies, then copy them to a fixed path (/prod_modules). This is the set the final image needs, kept apart from the dev dependencies the build pulls in next.
Build. Install the full dependency set, copy the source, and run the build. This stage holds the compiler, the dev dependencies, and the source, none of which ship.
Runtime. Start fresh from node:24, copy in the production node_modules and the built dist/, drop to uid 1001, and start. The toolchain stays behind.

Running a static frontend instead of a Node server? Build with node, then serve the built assets from nginx, or ship a self-contained binary onto static.
Pin by digest once you settle on a base, so every build runs exactly what was scanned and signed.

Edit this page on GitHub

Build a Node app

The multi-stage Dockerfile

What each stage does

Next