Resolving ESHOPMAN Storefront Build Failures: PNPM 12 Compatibility and Cloudflare Adapter Deployments

At Move My Store, we understand the critical importance of a smooth and reliable build process for your ESHOPMAN storefronts, especially when deploying through HubSpot CMS. ESHOPMAN, as a headless commerce platform wrapped as a HubSpot application, relies on robust underlying systems to ensure your storefronts are deployed efficiently. Recently, our community identified a significant challenge impacting ESHOPMAN Cloud storefront builds for users leveraging pnpm version 12.x in their projects.

The Core Problem: PNPM 12 Compatibility

The primary issue stems from how ESHOPMAN's Cloud deployment environment generates build scripts for storefronts. Specifically, the build-fe.sh script, which is part of the internal frontend-runner.js logic, uses the command pnpm add --save to install crucial dependencies like the @opennextjs/cloudflare adapter. However, pnpm 12 (the Rust port, including version 12.5.1) has deprecated and now rejects the --save flag, expecting --save-prod or -P for production dependencies.

When the build script attempts to run pnpm add --save @opennextjs/[email protected], pnpm 12 throws an error:

error: unexpected argument '--save' found

  tip: a similar argument exists: '--save-dev'

Usage: pnpm add --save-dev ...

This failure means the Cloudflare adapter is never installed, leading to the storefront build terminating with a fatal error: ./build-fe.sh: 12: /app/workdir//node_modules/.bin/opennextjs-cloudflare: not found. Consequently, while your ESHOPMAN backend might deploy successfully, the storefront build fails, preventing a complete and functional deployment to HubSpot CMS.

A simple reproduction command demonstrates this behavior:

corepack [email protected] add --save [email protected]     # error: unexpected argument '--save' found
corepack [email protected] add --save [email protected]    # works
corepack [email protected] add --save-prod [email protected]  # works

Secondary Challenge: Strict Dependency Builds and 'workerd'

A related issue, affecting pnpm 11.x and 12.x, concerns the installation of the wrangler dependency. ESHOPMAN's build script includes the line pnpm add --save-dev [email protected]. With pnpm's default strictDepBuilds setting, this command can fail with an ERR_PNPM_IGNORED_BUILDS error if the workerd package is not explicitly allowed in your project's pnpm-workspace.yaml file beforehand. The ESHOPMAN build process includes a step to run pnpm approve-builds workerd, but this step unfortunately executes *after* the wrangler installation attempt, making it ineffective in preventing the initial failure.

Impact on ESHOPMAN Deployments

This combination of issues means that ESHOPMAN storefronts configured to use pnpm 12.x will consistently fail during the Cloud build process. Even with pnpm 11.x, users might encounter build failures if they haven't manually pre-approved workerd in their pnpm-workspace.yaml.

Immediate Workarounds for ESHOPMAN Users

While the ESHOPMAN platform team works on a permanent fix (which would involve updating the generateBuildScripts logic to use --save-prod for pnpm and reordering the approve-builds step), here are some immediate workarounds:

• Pin PNPM to Version 11.x: Temporarily revert your project's packageManager setting to pnpm 11.x (e.g., "packageManager": "[email protected]") in your workspace root package.json.
• Pre-approve 'workerd': Ensure that workerd: true is explicitly added to the allowBuilds section of your pnpm-workspace.yaml file. This will prevent the strictDepBuilds error during the wrangler installation.

Conclusion

The ESHOPMAN community is actively addressing these build challenges to ensure a seamless development and deployment experience for all users. By understanding these technical intricacies and applying the suggested workarounds, you can maintain continuous integration and deployment of your ESHOPMAN storefronts via HubSpot CMS. We appreciate the detailed reports from our community members, which are invaluable in enhancing the robustness of the ESHOPMAN platform.