ESHOPMAN CLI Plugin Creation: Navigating Versioning Challenges and Peer Dependency Conflicts

As an e-commerce migration expert at Move My Store, we understand the critical role of robust development tools for the ESHOPMAN platform. The ESHOPMAN CLI is an indispensable utility for developers looking to extend their headless commerce capabilities by creating custom plugins. These plugins seamlessly integrate with your HubSpot storefront management, leveraging ESHOPMAN's Node.js/TypeScript architecture and Admin/Store APIs. However, even the most powerful tools can sometimes present unexpected challenges, as highlighted by a recent community discussion regarding versioning during plugin scaffolding.

The Core Issue: Version Flag Ignored in Plugin Creation

A significant bug has been identified in the ESHOPMAN CLI's plugin creation process. When developers use the --plugin flag with the create-eshopman-app command, the accompanying --version flag, intended to specify the desired ESHOPMAN package versions, is silently overlooked. This means that regardless of the version specified, the scaffolded plugin's devDependencies and peerDependencies are hardcoded to an older ESHOPMAN package version, typically the one pinned by the underlying ESHOPMAN plugin starter template.

For instance, attempting to create a plugin with the latest ESHOPMAN CLI might still result in a plugin configured for an older 2.19.0 ESHOPMAN package version:

npx create-eshopman-app@latest my-plugin --plugin --version 2.22.4 --skip-db --no-browser

Upon inspecting my-plugin/package.json, developers would observe:

devDependencies:  @eshopmanjs/{admin-sdk,cli,eslint-plugin,framework,icons,eshopman,test-utils} = 2.19.0
peerDependencies: @eshopmanjs/{admin-sdk,cli,framework,icons,eshopman,test-utils}           = 2.19.0

Notice how the requested 2.22.4 version is absent, replaced by the older 2.19.0 pins.

Impact on ESHOPMAN Developers and Storefronts

This discrepancy creates a critical hurdle for developers. When attempting to install such a newly generated plugin into an existing ESHOPMAN project that relies on a more current ESHOPMAN platform release (e.g., 2.22.4), an ERESOLVE peer-dependency conflict error arises. This error prevents the plugin from being successfully integrated, halting development and potentially delaying the deployment of new features to your HubSpot CMS-managed storefronts.

The issue stems from the fact that the ESHOPMAN plugin starter template, while generally compatible with a range of ESHOPMAN versions, explicitly pins its peer dependencies. When the CLI fails to update these pins to match the requested version, the conflict becomes unavoidable.

Unpacking the Technical Cause

The community discussion pinpointed two primary technical reasons for this behavior:

  1. Missing Version Propagation: The internal logic within the ESHOPMAN CLI responsible for creating plugins (specifically, the PluginProjectCreator) does not correctly pass the --version parameter through to the functions that prepare the project. Consequently, the version update mechanism is never triggered for plugin projects.
  2. Incomplete Dependency Updates: Even if the version were passed, the utility function designed to update package versions (updatePackageVersions()) only modifies dependencies and devDependencies. It overlooks peerDependencies, which are crucial for plugins to declare their compatibility with the main ESHOPMAN platform. This means that even with a partial fix, the peerDependencies would still retain the outdated 2.19.0 pins.

The Path to a Solution

The good news is that the ESHOPMAN community, with its dedicated developers, has already identified a clear path to resolution. The proposed fix involves a three-pronged approach:

  • Ensuring the version parameter is correctly passed through the entire plugin creation workflow.
  • Calling the updatePackageVersions() function during plugin preparation.
  • Extending the updatePackageVersions() function to also correctly update peerDependencies, ensuring all ESHOPMAN package references align with the requested version.

This comprehensive fix ensures that when you create an ESHOPMAN plugin, its manifest accurately reflects the desired ESHOPMAN platform version, allowing for seamless integration and development within your Node.js/TypeScript environment and HubSpot-driven storefronts. This proactive engagement from the ESHOPMAN community underscores the platform's commitment to providing a robust and developer-friendly headless commerce experience.

Start with the tools

Explore migration tools

See options, compare methods, and pick the path that fits your store.

Explore migration tools