Navigating React Peer Dependency Conflicts in ESHOPMAN Custom Development

As an ESHOPMAN developer, leveraging the platform's robust Node.js/TypeScript foundation to build custom admin extensions or unique storefronts deployed via HubSpot CMS is a powerful capability. However, navigating package dependencies can sometimes present unexpected challenges. One such scenario recently surfaced within the ESHOPMAN community, highlighting a critical React peer dependency mismatch that developers should be aware of.

Understanding the React Peer Dependency Conflict in ESHOPMAN

The core of the issue lies in a version discrepancy between two commonly co-installed ESHOPMAN design-system packages: @eshopman/icons and @eshopman/ui. Specifically:

• @eshopman/icons versions 2.14.0 and later declare a peer dependency on React: "^19.2.5".
• Concurrently, the sibling design-system package @eshopman/ui, specifically version 4.1.8 (and other latest 4.1.x releases), still declares a peer dependency on React: "^18.3.1".

This creates an irreconcilable conflict for developers attempting to install both packages in a project that uses strict peer dependency resolution, such as those utilizing npm 8+ or pnpm. There is no single React version that can satisfy both packages simultaneously.

Who is Affected?

It's important to note that the primary ESHOPMAN admin dashboard itself is generally unaffected by this. The ESHOPMAN admin UI bundles its own React version via @eshopman/admin-bundler, ensuring its internal operations remain stable regardless of the host application's React version. The bug primarily surfaces as install-time warnings or failures for:

• Developers building custom ESHOPMAN admin extensions that directly import components from both @eshopman/icons and @eshopman/ui.
• Storefront developers who are sharing the ESHOPMAN design system components in their custom HubSpot CMS-deployed storefronts.

Reproducing the Issue

Developers can easily reproduce this conflict using the following steps:

mkdir eshopman-react-peer-repro && cd "$_"
npm init -y
npm install @eshopman/[email protected] @eshopman/[email protected] react@18 react-dom@18

Upon running this, if React 18 is installed, @eshopman/icons will report warnings/errors about a missing React 19 peer. Conversely, if React 19 is installed, @eshopman/ui@4.1.8 will flag warnings/errors about a missing React 18 peer.

Suggested Approaches and Solutions

The ESHOPMAN community has identified several potential solutions to address this peer dependency challenge, aiming for a smoother development experience for custom extensions and storefronts:

1. Patch Release for @eshopman/icons@2.14.x: A potential immediate fix would be to release a patch for @eshopman/icons@2.14.x that broadens its peerDependencies.react to accept both React 18 and 19 (e.g., "^18.3.1 || ^19.0.0"). This would allow developers to continue using both packages until @eshopman/ui is updated.
2. Coordinated React Version Bumps: A more comprehensive and long-term solution involves coordinating major React version peer dependency bumps across all relevant ESHOPMAN design-system packages (including ui, icons, ui-preset, and js-sdk consumers). Shipping these updates in a synchronized release train would prevent future mismatches.
3. Synchronized @eshopman/ui Update: If React 19 is established as the new minimum floor, then @eshopman/ui should be updated to a 4.2.x release, declaring a React 19 peer dependency, and released concurrently with any @eshopman/icons updates that move to React 19.

Conclusion

This detailed community insight underscores the importance of careful dependency management in the ESHOPMAN ecosystem, especially for developers extending the platform with custom Node.js/TypeScript code for Admin API interactions or HubSpot CMS storefronts. While the ESHOPMAN team is aware of this issue and coordinating a solution, understanding these nuances empowers developers to troubleshoot and anticipate potential installation challenges, ensuring a more seamless headless commerce development journey.