Reusable Node.js LTS base images with pinned pnpm and npm, native build tools for development, and production runtimes for Node.js applications. Suitable for Next.js, Vite, APIs, workers, and other Node.js projects.
One image per Node.js major and purpose. Each tag includes linux/amd64 and linux/arm64; Docker selects the architecture automatically. These are Linux containers, also usable through Docker Desktop on macOS and Windows.
| Node major | Current Node version | Production | Development / build | Production + PostgreSQL 17 clients |
|---|---|---|---|---|
| 24 | 24.22.3 | 24 | 24-dev | 24-pg17 |
| 22 | 22.23.5 | 22 | 22-dev | 22-pg17 |
| 26 | 26.13.1 | 26 | 26-dev | 26-pg17 |
For example: ymnik13/node-pnpm:24-dev. Tags stay the same when a Node patch or
base package is updated. Exact versions are listed here, locked in versions.json,
and recorded in image metadata. There are no patch, date, OS, architecture, or
release-suffix tags. Production uses the plain major tag; no extra -prod alias
is needed. Use docker pull or docker build --pull to receive an updated image
within the selected major.
| Component | Runtime | Development | Runtime + PG17 |
|---|---|---|---|
| Node.js LTS, pnpm 11.28.12, npm 11.21.2 | Yes | Yes | Yes |
| CA certificates, libstdc++, tini | Yes | Yes | Yes |
Non-root node user, UID/GID 1000:1000 | Yes | Yes | Yes |
| C/C++ compiler, make, Python 3, pkg-config | — | Yes | — |
| Git, SSH client, bash, curl, jq, procps | — | Yes | SSH client and curl |
pg_dump, pg_restore, psql 17.x, util-linux | — | — | Yes |
The working directory is /app. Runtime images set NODE_ENV=production;
development images set NODE_ENV=development. tini forwards signals and reaps
child processes. The default command is node; applications supply their own
CMD. The base image does not install dependencies or run migrations at startup.
Frameworks and application tools stay in your project's lockfile: Next.js,
React, TypeScript, ESLint, Prettier, Vitest, Playwright, database libraries,
sharp, and other application dependencies are not installed globally. Run
your project scripts or use pnpm exec. Playwright browsers belong in a separate
test image matching the project's Playwright version.
# Check the runtime.
docker run --rm ymnik13/node-pnpm:24 node --version
# Check the development package manager.
docker run --rm ymnik13/node-pnpm:24-dev pnpm --version
# Optional PostgreSQL client runtime; no PostgreSQL server is included.
docker run --rm ymnik13/node-pnpm:24-pg17 pg_dump --version
This multi-stage Dockerfile uses the development image for dependency installation
and compilation, then copies Next.js standalone output into the production image.
Set output: 'standalone' in your Next.js configuration.
The example assumes pnpm-workspace.yaml and public/ exist. Adjust the COPY
instructions if your project does not use them; monorepos may also require
changes to standalone output paths and outputFileTracingRoot.
# syntax=docker/dockerfile:1.7
# Canonical major tags; exact versions are recorded in versions.json and image metadata.
ARG DEV_IMAGE=ymnik13/node-pnpm:24-dev
ARG RUNTIME_IMAGE=ymnik13/node-pnpm:24
FROM ${DEV_IMAGE} AS deps
ARG TARGETARCH
ARG CACHE_VARIANT=alpine
COPY --chown=node:node package.json pnpm-lock.yaml pnpm-workspace.yaml ./
RUN --mount=type=cache,id=myapp-pnpm11-${CACHE_VARIANT}-${TARGETARCH},target=/pnpm/store,uid=1000,gid=1000 \
pnpm install --frozen-lockfile --store-dir=/pnpm/store --package-import-method=copy
FROM deps AS dev
RUN mkdir -p /app/.next/cache
COPY --chown=node:node . .
ENV HOSTNAME=0.0.0.0
CMD ["pnpm", "dev"]
FROM deps AS build
ENV NODE_ENV=production
ARG TARGETARCH
ARG CACHE_VARIANT=alpine
COPY --chown=node:node . .
RUN mkdir -p /app/.next/cache
RUN --mount=type=cache,id=myapp-next-${CACHE_VARIANT}-${TARGETARCH},target=/app/.next/cache,uid=1000,gid=1000 \
pnpm build
FROM ${RUNTIME_IMAGE} AS production
ENV HOSTNAME=0.0.0.0 PORT=3000
COPY --from=build --chown=node:node /app/.next/standalone ./
COPY --from=build --chown=node:node /app/.next/static ./.next/static
COPY --from=build --chown=node:node /app/public ./public
EXPOSE 3000
CMD ["node", "server.js"]
Build the desired target:
docker build --target dev -t my-app:dev .
docker build --target production -t my-app:production .
For other Node.js applications, copy the compiled application and its required production dependencies into the runtime stage, then set the appropriate command. Keep Node major, C library, and architecture compatible across build and runtime.
Keep dependencies and build output in Linux volumes so host node_modules do
not replace container dependencies. For example:
services:
app:
build:
context: .
target: dev
ports: ["127.0.0.1:10201:3000"]
volumes:
- .:/app
- node_modules:/app/node_modules
- next_cache:/app/.next
- pnpm_store:/pnpm/store
command: [pnpm, dev]
volumes:
node_modules:
next_cache:
pnpm_store:
After changing the lockfile, update the dependency volume explicitly:
docker compose run --rm app pnpm install --frozen-lockfile --store-dir=/pnpm/store
Use fresh dependency/build volumes when switching Node major, distribution, or
architecture. Bind-mounted directories must be writable by UID 1000; changing
user: alone does not change file ownership. The image does not recursively
change ownership of your source files at startup.
/pnpm/store and Next.js
build data at /app/.next/cache between builds.npm_config_nodedir=/usr/local avoids downloading headers for node-gyp.npm ci; those projects should use their
own lockfile and npm cache configuration.The pnpm wrapper uses --pm-on-fail=ignore to keep the image's reviewed pnpm
version instead of silently downloading another version from packageManager.
Project policies such as allowBuilds, minimumReleaseAge, and trustPolicy
remain under the project's control. The base does not enable all dependency
build scripts or rewrite your lockfile.
Alpine uses musl, so validate native dependencies on each target architecture. The official Node Docker documentation classifies upstream Linux/amd64 musl builds as Experimental tier. Passing tests and a clean vulnerability scan do not extend upstream platform support guarantees.
The selected base OS is Alpine 3.23 for all majors. The publisher maintains one base per major, rather than a separate tag matrix for multiple distributions.
Scan results are a point-in-time check, not a guarantee against future issues. Review and rebuild base images regularly, and scan the final application image: its own dependencies and application code are outside the scope of this base.
Content type
Image
Digest
sha256:46e6cdc52…
Size
76.2 MB
Last updated
2 days ago
docker pull ymnik13/node-pnpm:26-pg17