nodejs-containers

# Node.js Container Optimization

Expert knowledge for building optimized Node.js container images using Alpine variants, multi-stage builds, and Node.js-specific dependency management patterns.

## Core Expertise

**Node.js Container Challenges**:
- Large node_modules directories (100-500MB)
- Full base images include build tools (~900MB)
- Separate dev and production dependencies
- Different package managers (npm, yarn, pnpm)
- Native modules requiring build tools

**Key Capabilities**:
- Alpine-based images (~100MB vs ~900MB full)
- Multi-stage builds separating build and runtime
- BuildKit cache mounts for node_modules
- Production-only dependency installation
- Non-root user configuration

## The Optimization Journey: 900MB → 50-100MB

### Step 1: The Problem - Full Node Base (900MB)

```dockerfile
# ❌ BAD: Includes full Debian, all dependencies, build tools
FROM node:20
WORKDIR /app
COPY . .
RUN npm install
EXPOSE 3000
CMD ["node", "server.js"]
```

**Issues**:
- Full Debian base (~120MB)
- All npm dependencies including devDependencies
- Build tools and compilers for native modules
- Source files and tests in production image

**Image size: ~900MB**

### Step 2: Alpine Base (350MB)

```dockerfile
# ✅ BETTER: Alpine reduces OS overhead
FROM node:20-alpine
WORKDIR /app
COPY . .
RUN npm install
EXPOSE 3000
CMD ["node", "server.js"]
```

**Improvements**:
- Alpine Linux (~5MB vs ~120MB Debian)
- Still includes all dependencies (dev + prod)
- Still includes source files

**Image size: ~350MB** (61% reduction)

### Step 3: Production Dependencies Only (200MB)

```dockerfile
# ✅ GOOD: Only production dependencies
FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
EXPOSE 3000
USER node
CMD ["node", "server.js"]
```

**Improvements**:
- Only production dependencies
- Running as non-root user
- Better layer caching (package.json separate)

**Image size: ~200MB** (43% reduction from 350MB)

### Step 4: Multi-Stage Build for Stat