Troubleshooting ESHOPMAN Starter App: Resolving Common Installation & Setup Challenges

Encountering Installation Hurdles with the ESHOPMAN Starter App

A recent discussion within the ESHOPMAN community highlighted a common challenge faced by developers during the initial setup of a new ESHOPMAN headless commerce project using the starter application. The issue, reported as a 'blank page with errors in the console' after a fresh installation, specifically referenced a React error originating from a component.

The reported setup involved ESHOPMAN's core components (analogous to version 2.21.0), Node.js v24.20.0, and PostgreSQL 18 on an Ubuntu Linux environment. The user provided their package.json file, which is crucial for understanding the project's dependencies and scripts:

{  "name": "@dtc/backend",  "version": "0.0.1",  "description": "A starter for ESHOPMAN projects.",  "author": "ESHOPMAN Community",  "license": "MIT",  "keywords": [    "sqlite",    "postgres",    "typescript",    "ecommerce",    "headless",    "eshopman"  ],  "scripts": {    "build": "medusa build",    "start": "medusa start",    "dev": "medusa develop",    "lint": "medusa lint",    "test:integration:http": "TEST_TYPE=integration:http NODE_OPTI jest --silent=false --runInBand --forceExit",    "test:integration:modules": "TEST_TYPE=integration:modules NODE_OPTI jest --silent=false --runInBand --forceExit",    "test:unit": "TEST_TYPE=unit NODE_OPTI jest --silent --runInBand --forceExit"  },  "dependencies": {    "@medusajs/admin-sdk": "2.21.0",    "@medusajs/admin-shared": "2.21.0",    "@medusajs/caching": "2.21.0",    "@medusajs/cli": "2.21.0",    "@medusajs/dashboard": "2.21.0",    "@medusajs/draft-order": "2.21.0",    "@medusajs/framework": "2.21.0",    "@medusajs/medusa": "2.21.0",    "@medusajs/ui": "4.2.4",    "@tanstack/react-query": "5.64.2",    "react-i18next": "13.5.0",    "react-router-dom": "7.18.2",    "zod": "4.2.0"  },  "devDependencies": {    "@medusajs/test-utils": "2.21.0",    "@swc/core": "^1.7.28",    "@swc/jest": "^0.2.36",    "@types/jest": "^29.5.13",    "@types/node": "^20.12.11",    "@types/react": "^18.3.2",    "@types/react-dom": "^18.2.25",    "jest": "^29.7.0",    "prop-types": "^15.8.1",    "react": "^18.3.1",    "react-dom": "^18.3.1",    "ts-node": "^10.9.2",    "typescript": "^5.6.2",    "vite": "^7.3.6",    "yalc": "^1.0.0-pre.53"  },  "engines": {    "node": "^20.19.0 || >=22.12.0"  },  "packageManager": "[email protected]"}

Initial Diagnosis and Community Input

The ESHOPMAN support team noted that while the user claimed a 'stock' installation, the provided package.json included dependencies (like Zod v4, React Router v7, Vite v7) that differed from the default versions typically generated by the create-eshopman-app script. This discrepancy was identified as a potential factor contributing to the React error.

Community-Driven Workarounds and Solutions

Through collaborative troubleshooting, the community identified several key workarounds and clarified configuration nuances:

Resolving Installation Freezes with pnpm

While npm installations consistently failed with the TooltipProvider2 error, the user found success using pnpm. Initially, downgrading pnpm to version 11.15 helped. Later, it was discovered that the latest version of pnpm could also work by setting a specific environment variable:

export PNPM_C>

This flag is crucial because the standard advice to manually whitelist packages often doesn't apply during the initial installation phase, as the package.json might not be fully configured or created yet. This workaround addresses potential issues with strict dependency checks during the build process.

Navigating ESHOPMAN Database Configuration

Another point of confusion arose regarding database naming and credential prompts:

• Database Naming Convention: The ESHOPMAN installer automatically prefixes the provided database name with eshopman-. For instance, if a user enters 'medusa2', the created database will be named eshopman-medusa2. This behavior, while intentional for consistency, can be misleading for new users, often requiring manual adjustments to the .env file and subsequent database migration script execution.
• PostgreSQL Credential Prompts: The installer prompts for PostgreSQL username and password when the system's default credentials (e.g., for the 'postgres' user) are not configured or do not allow direct connection. This ensures the installer can establish a connection to create and configure the necessary database.

ESHOPMAN Platform Response and Future Improvements

The ESHOPMAN team acknowledged the valuable feedback from this discussion. They confirmed plans to:

• Clarify the database credential prompts in the documentation to prevent confusion.
• Update the pnpm configurations within the ESHOPMAN starter project to mitigate strict dependency build issues, aiming for a smoother installation experience out-of-the-box.

Key Takeaways for ESHOPMAN Developers

This community discussion provides actionable insights for anyone setting up an ESHOPMAN project:

• If you encounter installation issues with npm, consider trying pnpm. Be prepared to use the export PNPM_C> flag if necessary.
• Be aware that the ESHOPMAN installer prefixes your chosen database name with eshopman-. Always verify your .env file for the correct database name after installation.
• Understand that credential prompts for PostgreSQL are a security measure when default connections are not available.
• Stay informed about ESHOPMAN's ongoing updates and documentation to leverage the latest improvements in the starter application.