Gotcha: Docker layer caching invalidation

Docker builds are slow because layer caching keeps getting invalidated, rebuilding layers that haven't changed.

Docker layer caching rules and how to optimize:

# RULE: If a layer changes, ALL subsequent layers are invalidated

# BAD: Any code change invalidates npm install
COPY . .                    # Layer 1: copies everything
RUN npm install              # Layer 2: always re-runs!

# GOOD: Separate dependency and code layers
COPY package*.json ./        # Layer 1: only package files
RUN npm ci                   # Layer 2: cached if package.json unchanged
COPY . .                     # Layer 3: code changes here
RUN npm run build            # Layer 4: only re-runs if code changed

# ORDER BY CHANGE FREQUENCY (least -> most)
# 1. System dependencies (rarely change)
# 2. Language/runtime setup
# 3. Dependency files (change occasionally)
# 4. Source code (changes frequently)
# 5. Build step

More tips:

# Use .dockerignore to prevent unnecessary cache busts
# .dockerignore:
# node_modules
# .git
# *.md
# .env

# Multi-stage: build cache preserved even if final image changes
FROM node:20 AS deps
COPY package*.json ./
RUN npm ci               # Cached independently

FROM node:20
COPY --from=deps /app/node_modules ./node_modules
COPY . .

# Use BuildKit mount cache for package managers
RUN --mount=type=cache,target=/root/.npm npm ci

Docker builds layers sequentially. A change in any layer invalidates all layers after it. Proper ordering can reduce build time from minutes to seconds.

Optimizing Docker build times in development and CI