low-code-react-app-b/docs/CI_CD_FIX_OVERRIDES.md

CI/CD Fix Summary

Problem Solved

The project was failing in CI/CD with the following errors:

1. npm ci failures due to workspace protocol not being recognized:

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

2. Lock file sync issues due to version mismatches:

   npm error Invalid: lock file's @github/spark@0.0.1 does not satisfy @github/spark@0.44.15
   

3. Peer dependency conflicts requiring --legacy-peer-deps flag

Solution Implemented

1. Replaced Workspace Protocol

Changed from workspace:* to file:./packages/spark-tools for better compatibility.

2. Added Dependency Overrides

Added overrides section to package.json to force consistent versions:

"overrides": {
  "react": "^19.0.0",
  "react-dom": "^19.0.0",
  "@types/react": "^19.0.10",
  "@types/react-dom": "^19.0.4",
  "vite": "^7.3.1",
  "@github/spark": {
    "react": "^19.0.0",
    "vite": "^7.3.1"
  },
  "@local/spark-wrapper": {
    "react": "^19.0.0"
  }
}

Impact

Before

• ❌ Required --legacy-peer-deps flag
• ❌ CI/CD builds failing with EUNSUPPORTEDPROTOCOL
• ❌ Inconsistent dependency versions
• ❌ Lock file constantly out of sync

After

• ✅ No special flags required
• ✅ Standard npm ci works in CI/CD
• ✅ Consistent versions across all packages
• ✅ Lock file stays in sync

Next Steps

1. Run locally to update the lock file:

   npm install
   

2. Commit the changes:

   git add package.json package-lock.json
   git commit -m "fix: remove workspace protocol and add overrides for CI/CD compatibility"
   git push
   

3. Verify CI/CD: GitHub Actions should now pass without modifications to workflow files

Technical Details

Why file: Over workspace:

• Standard npm support: file: is supported by all npm versions
• CI/CD compatibility: Works without special tooling or flags
• Transparent resolution: npm treats it like any other local dependency

Why Overrides Matter

The overrides field in package.json (npm 8.3.0+) provides:

• Centralized version control for transitive dependencies
• Resolution of peer dependency conflicts
• Consistency across monorepo packages
• No need for resolutions/peerDependenciesMeta workarounds

Compatibility

• ✅ npm >= 8.3.0 (for overrides support)
• ✅ Node.js >= 16.x
• ✅ GitHub Actions runners (current)
• ✅ Docker builds
• ✅ Local development

Rollback Plan

If issues arise, revert to previous configuration:

git revert HEAD
npm install --legacy-peer-deps

Then update CI workflows to use npm install --legacy-peer-deps instead of npm ci.