metabuilder/frontends/codegen/docs/CI_CD_QUICK_REFERENCE.md

CI/CD Quick Reference

Working with npm Workspaces

This project uses npm workspaces to manage the @github/spark monorepo package. Always use the correct install command:

✅ Correct Commands

# Local development
npm install --workspaces --legacy-peer-deps

# CI/CD (already configured in workflows)
npm install --workspaces --legacy-peer-deps

# Docker builds (already configured in Dockerfile)
npm install --workspaces --include-workspace-root

❌ Commands to Avoid

# Will fail with workspace protocol error
npm ci

# Will not properly link workspace packages
npm install

Docker Build

Build Locally

docker build -t codeforge:local .

Test Locally

docker run -p 8080:80 codeforge:local
# Open http://localhost:8080

Prerequisites

• Ensure packages/spark-tools/dist exists and is built
• If missing, run: cd packages/spark-tools && npm run build

GitHub Actions Status

All workflows are configured to use workspace-aware commands:

• ✅ ci.yml - Main CI/CD pipeline
• ✅ e2e-tests.yml - End-to-end tests
• ✅ release.yml - Release automation

Troubleshooting

"Unsupported URL Type: workspace:"

Cause: Using npm ci or npm install without workspace flags

Fix: Use npm install --workspaces --legacy-peer-deps

Docker build fails with dependency errors

Cause: Missing packages/spark-tools/dist folder

Fix:

cd packages/spark-tools
npm install
npm run build
cd ../..

Peer dependency conflicts

Cause: React 19 and some packages have peer dependency mismatches

Fix: Always use --legacy-peer-deps flag (already in all workflows)

Common Tasks

Add a new dependency

npm install <package> --workspaces --legacy-peer-deps

Update dependencies

npm update --workspaces --legacy-peer-deps

Clean install (reset node_modules)

rm -rf node_modules package-lock.json
rm -rf packages/*/node_modules
npm install --workspaces --legacy-peer-deps

Build for production

npm run build

Run locally

npm run dev

Links

• Docker Build Fix Documentation
• Main CI/CD Workflow
• npm Workspaces Documentation