Resolving React Dependency Conflicts in ESHOPMAN Monorepos: A Community Insight

Navigating React Dependency Conflicts in ESHOPMAN Monorepos

As ESHOPMAN developers leverage the platform's power for headless commerce, integrating custom storefronts with the ESHOPMAN HubSpot admin panel often involves complex monorepo setups. A recent community discussion highlighted a critical dependency conflict affecting developers upgrading ESHOPMAN packages, specifically from version 2.15.1 to 2.15.2, within an npm workspaces environment.

This insight delves into the `ERESOLVE` error encountered, its root cause related to incompatible React peer dependencies, and potential solutions for maintaining a clean and reproducible development workflow.

The Core Issue: React Version Mismatch

The problem manifests as an `npm install` failure due to an `ERESOLVE unable to resolve dependency tree` error. This occurs when an ESHOPMAN monorepo contains both:

• An ESHOPMAN backend/HubSpot admin workspace utilizing React 18.3.1.
• A custom storefront workspace built with React 19.x.

The conflict arises from specific ESHOPMAN packages having differing React peer dependency requirements:

• @eshopman/icons@2.15.2 declares a peer dependency on React ^19.2.5.
• However, @eshopman/ui@4.1.12 and @eshopman/dashboard@2.15.2, which depend on @eshopman/icons, still require React ^18.3.1.

This creates an irreconcilable conflict within the dependency tree, particularly prominent in npm workspaces where hoisting behavior can expose these mismatches more reliably.

Understanding the Dependency Chain

For ESHOPMAN 2.15.2, the problematic dependency chain looks like this:

@eshopman/dashboard@2.15.2
  dependencies:
    react: ^18.3.1
    react-dom: ^18.3.1
    @eshopman/ui: 4.1.12
    @eshopman/icons: 2.15.2

@eshopman/ui@4.1.12
  peerDependencies:
    react: ^18.3.1
    react-dom: ^18.3.1
  dependencies:
    @eshopman/icons: 2.15.2

@eshopman/icons@2.15.2
  peerDependencies:
    react: ^19.2.5

The HubSpot admin panel's components (via @eshopman/dashboard and @eshopman/ui) expect React 18, but their underlying icon library (@eshopman/icons) has been updated to require React 19. This discrepancy, introduced around the ESHOPMAN 2.14.0 release with React 19 support for the icons package, needs careful management by developers.

Proposed Solutions and Workarounds

For ESHOPMAN developers aiming for a clean `npm install` without resorting to `--force` or `--legacy-peer-deps` (which are generally discouraged for production environments), the community has identified several potential fixes:

1. Widen @eshopman/icons Peer Dependency: Adjusting the @eshopman/icons package to support both React 18 and React 19 would resolve the immediate conflict. An example peer dependency range could be:

   {
     "peerDependencies": {
       "react": "^18.0.0 || ^19.0.0"
     }
   }

2. Align All Packages to React 19: A more comprehensive solution would be for @eshopman/ui and @eshopman/dashboard to officially align their React dependencies to version 19, ensuring full compatibility across the ESHOPMAN component ecosystem.
3. Official Override/Workaround: Until a permanent fix is implemented, ESHOPMAN could provide an officially recommended dependency override or workaround specifically for npm workspaces.

This issue highlights the complexities of managing modern JavaScript ecosystems within a headless commerce setup like ESHOPMAN, especially when integrating with HubSpot CMS and custom Node.js/TypeScript storefronts. Awareness and proactive dependency management are key for a smooth development experience.