Node.js with pnpm

🐳 Annotated Dockerfile for Node.js with pnpm:

# Use Node.js LTS as the base image for consistency and long-term support
FROM node:lts-jod AS base

# Stage 1: Install production dependencies using pnpm
FROM base AS deps

# Enable corepack (manages package managers like pnpm)
RUN corepack enable

# Set working directory
WORKDIR /app

# Copy only package definition files first
COPY package.json pnpm-lock.yaml ./

# Cache the pnpm store for faster dependency fetches across builds
RUN --mount=type=cache,id=pnpm,target=/root/.local/share/pnpm/store \
 pnpm fetch --frozen-lockfile

# Install only production dependencies
RUN --mount=type=cache,id=pnpm,target=/root/.local/share/pnpm/store \
 pnpm install --frozen-lockfile --prod

# Stage 2: Build the application
FROM base AS build

# Enable corepack (manages package managers like pnpm)
RUN corepack enable

WORKDIR /app

# Copy package definitions to maintain consistent build context
COPY package.json pnpm-lock.yaml ./

# Reuse cached pnpm store for quick dependency installation
RUN --mount=type=cache,id=pnpm,target=/root/.local/share/pnpm/store \
 pnpm fetch --frozen-lockfile

# Install all dependencies (dev + prod) for building the app
RUN --mount=type=cache,id=pnpm,target=/root/.local/share/pnpm/store \
 pnpm install --frozen-lockfile

# Copy entire source code
COPY . .

# Run build script defined in your package.json (generally builds into a "dist" directory)
RUN pnpm build

# Stage 3: Create the final lightweight production image
FROM base

# Set working directory
WORKDIR /app

# Copy only production dependencies (no dev dependencies)
COPY --from=deps /app/node_modules /app/node_modules

# Copy compiled application output (dist directory)
COPY --from=build /app/dist /app/dist

# Explicitly set environment to production
ENV NODE_ENV production

# Default command to run your Node.js application
CMD ["node", "./dist/index.js"]

🔍 Why these are best practices:

✅ Multi-stage builds

Smaller final images: Dependencies and build tools are discarded after use, reducing container size.
Security: Fewer files and tools mean a smaller attack surface.

✅ Caching pnpm store

Faster builds: Reusing a cached store reduces install times drastically, especially beneficial for large dependency trees.
Lower CI/CD overhead: Speeds up continuous integration and deployment workflows.

✅ Separating dependencies and build stages

Clear separation of concerns: Each stage serves a single purpose, making it easier to debug and optimize.
Improved cache efficiency: Changes in code don’t trigger unnecessary reinstallation of unchanged dependencies.

✅ Minimal runtime image

Performance and security: Only the essential runtime code is present, limiting potential vulnerabilities.
Lower resource consumption: Optimized resource usage in production deployments.

🚀 Additional Dockerfile best practices you can adopt:

Use a non-root user

For enhanced security, run your app as a non-root user:

FROM base

# Create a non-root user
RUN useradd -m appuser

WORKDIR /app

COPY --from=deps /app/node_modules /app/node_modules
COPY --from=build /app/dist /app/dist

ENV NODE_ENV production

# Switch to non-root user
USER appuser

CMD ["node", "./dist/index.js"]

Use HEALTHCHECK directive

Allows Docker to monitor container health automatically.

HEALTHCHECK --interval=30s --timeout=3s \
 CMD curl -f http://localhost:3000/health || exit 1

Use explicit .dockerignore

Prevent copying unnecessary files into your image.

Example .dockerignore

node_modules dist coverage .git Dockerfile docker-compose.yml README.md *.log


#### Set resource limits explicitly

When deploying containers, always set CPU and memory limits to avoid resource starvation or instability.

Example in Kubernetes or Docker Compose (outside Dockerfile)

```yaml
resources:
  limits:
    cpu: 1000m
    memory: 1Gi

Consider using Distroless or Alpine images

Switch to even lighter-weight base images if you’re comfortable handling potential compatibility issues:

FROM node:22-alpine AS base

Or distroless:

FROM gcr.io/distroless/nodejs22-debian12 AS final

By following these annotations and best practices, your Docker images become faster to build, more secure, smaller, and easier to maintain—ideal for modern production workflows.