ESHOPMAN pnpm Storefront Installation Fix & Monorepo Guide

Understanding ESHOPMAN Storefront Installation Challenges with pnpm

Setting up your ESHOPMAN headless commerce storefront, especially with specific package managers like pnpm, can sometimes present unexpected hurdles. A recent community discussion highlighted a recurring issue where the create-eshopman-app CLI tool encountered conflicts when attempting to install the Next.js Starter Storefront using pnpm.

The core of the problem stems from the starter storefront's package.json file, which explicitly designates Yarn as its preferred package manager via the "packageManager": "yarn@4.12.0" field. This conflicts with attempts to use pnpm for installation, leading to errors from Corepack, Node.js's package manager manager.

The Root Cause: package.json Configuration

Here's an example of the configuration that caused the conflict within the ESHOPMAN Next.js Starter Storefront's package.json:

{
  "name": "eshopman-next",
  "version": "1.0.3",
  "private": true,
  "author": "ESHOPMAN Team (https://www.eshopman.com)",
  "description": "Next.js Starter to be used with ESHOPMAN",
  "keywords": [
    "eshopman-storefront"
  ],
  "scripts": {
    "dev": "next dev --turbopack -p 8000",
    "build": "next build",
    "start": "next start -p 8000",
    "lint": "next lint",
    "analyze": "ANALYZE=true next build"
  },
  "dependencies": {
    "@headlessui/react": "^2.2.0",
    "@eshopman/icons": "latest",
    "@eshopman/js-sdk": "latest",
    "@eshopman/ui": "latest",
    "@radix-ui/react-accordion": "^1.2.1",
    "@stripe/react-stripe-js": "^5.3.0",
    "@stripe/stripe-js": "^8.2.0",
    "lodash": "^4.17.21",
    "next": "15.3.9",
    "pg": "^8.11.3",
    "qs": "^6.12.1",
    "react": "19.0.4",
    "react-country-flag": "^3.1.0",
    "react-dom": "19.0.4",
    "server-only": "^0.0.1",
    "tailwindcss-radix": "^2.8.0",
    "webpack": "^5"
  },
  "devDependencies": {
    "@babel/core": "^7.17.5",
    "@eshopman/types": "latest",
    "@eshopman/ui-preset": "latest",
    "@types/lodash": "^4.14.195",
    "@types/node": "17.0.21",
    "@types/pg": "^8.11.0",
    "@types/react": "19.0.3",
    "@types/react-dom": "19.0.3",
    "@types/react-instantsearch-dom": "^6.12.3",
    "ansi-colors": "^4.1.3",
    "autoprefixer": "^10.4.2",
    "babel-loader": "^8.2.3",
    "eslint": "8.10.0",
    "eslint-config-next": "15.0.8",
    "postcss": "^8.4.8",
    "prettier": "^2.8.8",
    "tailwindcss": "^3.0.23",
    "typescript": "^5.3.2"
  },
  "resolutions": {
    "@types/react": "19.0.4",
    "@types/react-dom": "19.0.4"
  },
  "overrides": {
    "react": "19.0.4",
    "react-dom": "19.0.4"
  },
  "packageManager": "yarn@4.12.0"
}

Common Installation Errors

Users experienced various errors when attempting to use pnpm:

Running pnpm dlx create-eshopman-app@latest my-eshopman-store:

An error occurred while installing Next.js Starter Storefront: Error: Command failed: pnpm install
 ERROR  This project is configured to use yarn
For help, run: pnpm help install

Using pnpm create eshopman-app@latest --skip-db:

UsageError: This project is configured to use yarn because storefront/package.json has a "packageManager" field

Attempting npx create-eshopman-app@latest --use-pnpm --skip-db:

The specified package manager "pnpm" is not available. Please install it or choose another package manager.

Temporary Solution & Documentation Clarifications

An ESHOPMAN team member, shahednasser, quickly addressed the issue by providing a snapshot version of the CLI tool. Users confirmed that installing with this specific snapshot resolved the immediate pnpm conflict:

pnpm dlx create-eshopman-app@2.13.2-snapshot-20260202072528

Additionally, the discussion highlighted a minor typo in the ESHOPMAN documentation regarding the pnpm command, where create medusa-app was mistakenly used instead of create-medusa-app. This has been noted for correction to ensure clearer guidance for developers.

Monorepo Considerations with pnpm Workspaces

For developers leveraging pnpm workspaces for monorepo setups, it was clarified that while the CLI installation issues were being addressed, native support for monorepos within ESHOPMAN is still under development. This means that for complex setups, certain ESHOPMAN packages might still require manual addition to the backend, even with public hoisting configured via .npmrc. The ESHOPMAN team anticipates adding native monorepo support in the upcoming months.

Key Takeaways for ESHOPMAN Developers

Stay Updated: Always check for the latest CLI versions or snapshots for known issues.
Verify package.json: Be aware of the packageManager field in starter templates, as it dictates the preferred package manager.
Documentation Accuracy: Refer to the official ESHOPMAN documentation, but be mindful that minor discrepancies can occur and are actively being resolved.
Monorepo Planning: If you're building a monorepo with pnpm workspaces, be prepared for some manual configuration until native support is fully rolled out.

The ESHOPMAN community and development team are committed to providing a seamless experience for building powerful headless commerce solutions. This collaborative effort to identify and resolve installation challenges ensures that developers can focus on innovation rather than setup complexities.

Navigating ESHOPMAN Storefront Setup: Resolving pnpm Package Manager Conflicts