metabuilder/frontends/codegen/docs/DOCKER_BUILD_FIX.md

Docker Build Fix - Workspace Protocol Resolution

Problem Summary

The Docker build was failing with the error:

npm error code EUNSUPPORTEDPROTOCOL
npm error Unsupported URL Type "workspace:": workspace:*

This occurred because:

1. The package.json uses "@github/spark": "workspace:*" to reference the local workspace package
2. npm's standard install doesn't properly resolve workspace protocols without the full workspace structure
3. The Dockerfile wasn't copying the complete workspace setup needed for proper dependency resolution

Solution Implemented

1. Updated Dockerfile

The Dockerfile now properly handles npm workspaces:

FROM node:20-alpine AS builder

WORKDIR /app

# Copy workspace configuration and all package files
COPY package*.json ./

# Copy spark-tools package (the actual @github/spark implementation)
COPY packages/spark-tools/package.json ./packages/spark-tools/package.json
COPY packages/spark-tools/dist ./packages/spark-tools/dist

# Copy spark wrapper package
COPY packages/spark/package.json ./packages/spark/package.json
COPY packages/spark/src ./packages/spark/src
COPY packages/spark/tsconfig.json ./packages/spark/tsconfig.json

# Install dependencies using npm workspaces
RUN npm install --workspaces --include-workspace-root

# Copy remaining application files
COPY . .

# Build the application
RUN npm run build

Key changes:

• Copies the complete workspace structure (both packages/spark and packages/spark-tools)
• Uses npm install --workspaces --include-workspace-root to properly resolve workspace dependencies
• Includes the pre-built dist folder from spark-tools (required for the build)

2. Updated .dockerignore

Modified to exclude build artifacts but preserve the essential spark-tools/dist:

node_modules
npm-debug.log
.git
.github
*.md
!README.md

# Keep the dist folder in packages/spark-tools (needed for build)
!packages/spark-tools/dist

3. Updated GitHub Actions Workflows

All npm install commands in .github/workflows/ci.yml now use:

npm install --workspaces --legacy-peer-deps

This ensures:

• Proper workspace resolution in CI
• Consistent behavior between local development and CI
• Avoids peer dependency conflicts

Why This Works

1. Workspace Protocol: npm workspaces require the full workspace structure to resolve workspace:* dependencies
2. Pre-built Assets: The spark-tools/dist folder contains the compiled @github/spark package that the main app depends on
3. Consistent Commands: Using --workspaces flag ensures npm properly links local packages

Testing the Fix

Local Docker Build

docker build -t codeforge:test .

GitHub Actions

The fix will automatically apply when you push to main or develop branches. The workflow will:

1. Install dependencies with workspace support
2. Build the Docker image using the updated Dockerfile
3. Push to GitHub Container Registry

Alternative Solutions Considered

1. Remove workspace protocol: Replace workspace:* with file paths - rejected because it breaks the monorepo structure
2. Use pnpm: Better workspace support - rejected because it requires changing the entire toolchain
3. Flatten dependencies: Copy spark into node_modules - rejected because it's a workaround, not a fix

Maintenance Notes

• Always ensure packages/spark-tools/dist is built before creating Docker images
• If you modify workspace structure, update the Dockerfile COPY commands accordingly
• The --legacy-peer-deps flag may be removed once all peer dependencies are resolved