docs: add troubleshooting guide for pnpm installations (medusajs#13351)

Author: shahednasser

www/apps/book/public/llms-full.txt

@@ -41235,7 +41235,7 @@ Connection to Redis in module 'workflow-engine-redis' established
 - [fetchShippingOptionForOrderWorkflow](https://docs.medusajs.com/references/medusa-workflows/fetchShippingOptionForOrderWorkflow/index.html.md)
 - [getOrderDetailWorkflow](https://docs.medusajs.com/references/medusa-workflows/getOrderDetailWorkflow/index.html.md)
 - [getOrdersListWorkflow](https://docs.medusajs.com/references/medusa-workflows/getOrdersListWorkflow/index.html.md)
-- [listShippingOptionsForOrderWorkflow](https://docs.medusajs.com/references/core_flows/Order/Workflows_Order/functions/core_flows.Order.Workflows_Order.listShippingOptionsForOrderWorkflow/index.html.md)
+- [listShippingOptionsForOrderWorkflow](https://docs.medusajs.com/references/medusa-workflows/listShippingOptionsForOrderWorkflow/index.html.md)
 - [markOrderFulfillmentAsDeliveredWorkflow](https://docs.medusajs.com/references/medusa-workflows/markOrderFulfillmentAsDeliveredWorkflow/index.html.md)
 - [markPaymentCollectionAsPaid](https://docs.medusajs.com/references/medusa-workflows/markPaymentCollectionAsPaid/index.html.md)
 - [maybeRefreshShippingMethodsWorkflow](https://docs.medusajs.com/references/medusa-workflows/maybeRefreshShippingMethodsWorkflow/index.html.md)
@@ -41392,11 +41392,11 @@ Connection to Redis in module 'workflow-engine-redis' established
 - [deleteSalesChannelsWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteSalesChannelsWorkflow/index.html.md)
 - [linkProductsToSalesChannelWorkflow](https://docs.medusajs.com/references/medusa-workflows/linkProductsToSalesChannelWorkflow/index.html.md)
 - [updateSalesChannelsWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateSalesChannelsWorkflow/index.html.md)
-- [createViewConfigurationWorkflow](https://docs.medusajs.com/references/core_flows/Settings/Workflows_Settings/functions/core_flows.Settings.Workflows_Settings.createViewConfigurationWorkflow/index.html.md)
-- [updateViewConfigurationWorkflow](https://docs.medusajs.com/references/core_flows/Settings/Workflows_Settings/functions/core_flows.Settings.Workflows_Settings.updateViewConfigurationWorkflow/index.html.md)
-- [createShippingOptionTypesWorkflow](https://docs.medusajs.com/references/core_flows/Shipping_Options/Workflows_Shipping_Options/functions/core_flows.Shipping_Options.Workflows_Shipping_Options.createShippingOptionTypesWorkflow/index.html.md)
-- [deleteShippingOptionTypesWorkflow](https://docs.medusajs.com/references/core_flows/Shipping_Options/Workflows_Shipping_Options/functions/core_flows.Shipping_Options.Workflows_Shipping_Options.deleteShippingOptionTypesWorkflow/index.html.md)
-- [updateShippingOptionTypesWorkflow](https://docs.medusajs.com/references/core_flows/Shipping_Options/Workflows_Shipping_Options/functions/core_flows.Shipping_Options.Workflows_Shipping_Options.updateShippingOptionTypesWorkflow/index.html.md)
+- [createViewConfigurationWorkflow](https://docs.medusajs.com/references/medusa-workflows/createViewConfigurationWorkflow/index.html.md)
+- [updateViewConfigurationWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateViewConfigurationWorkflow/index.html.md)
+- [createShippingOptionTypesWorkflow](https://docs.medusajs.com/references/medusa-workflows/createShippingOptionTypesWorkflow/index.html.md)
+- [deleteShippingOptionTypesWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteShippingOptionTypesWorkflow/index.html.md)
+- [updateShippingOptionTypesWorkflow](https://docs.medusajs.com/references/medusa-workflows/updateShippingOptionTypesWorkflow/index.html.md)
 - [deleteShippingProfileWorkflow](https://docs.medusajs.com/references/medusa-workflows/deleteShippingProfileWorkflow/index.html.md)
 - [validateStepShippingProfileDelete](https://docs.medusajs.com/references/medusa-workflows/validateStepShippingProfileDelete/index.html.md)
 - [createLocationFulfillmentSetWorkflow](https://docs.medusajs.com/references/medusa-workflows/createLocationFulfillmentSetWorkflow/index.html.md)
@@ -41668,13 +41668,13 @@ Connection to Redis in module 'workflow-engine-redis' established
 - [detachLocationsFromSalesChannelsStep](https://docs.medusajs.com/references/medusa-workflows/steps/detachLocationsFromSalesChannelsStep/index.html.md)
 - [detachProductsFromSalesChannelsStep](https://docs.medusajs.com/references/medusa-workflows/steps/detachProductsFromSalesChannelsStep/index.html.md)
 - [updateSalesChannelsStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateSalesChannelsStep/index.html.md)
-- [createViewConfigurationStep](https://docs.medusajs.com/references/core_flows/Settings/Steps_Settings/functions/core_flows.Settings.Steps_Settings.createViewConfigurationStep/index.html.md)
-- [setActiveViewConfigurationStep](https://docs.medusajs.com/references/core_flows/Settings/Steps_Settings/functions/core_flows.Settings.Steps_Settings.setActiveViewConfigurationStep/index.html.md)
-- [updateViewConfigurationStep](https://docs.medusajs.com/references/core_flows/Settings/Steps_Settings/functions/core_flows.Settings.Steps_Settings.updateViewConfigurationStep/index.html.md)
-- [createShippingOptionTypesStep](https://docs.medusajs.com/references/core_flows/Shipping_Options/Steps_Shipping_Options/functions/core_flows.Shipping_Options.Steps_Shipping_Options.createShippingOptionTypesStep/index.html.md)
-- [deleteShippingOptionTypesStep](https://docs.medusajs.com/references/core_flows/Shipping_Options/Steps_Shipping_Options/functions/core_flows.Shipping_Options.Steps_Shipping_Options.deleteShippingOptionTypesStep/index.html.md)
+- [createViewConfigurationStep](https://docs.medusajs.com/references/medusa-workflows/steps/createViewConfigurationStep/index.html.md)
+- [setActiveViewConfigurationStep](https://docs.medusajs.com/references/medusa-workflows/steps/setActiveViewConfigurationStep/index.html.md)
+- [updateViewConfigurationStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateViewConfigurationStep/index.html.md)
+- [createShippingOptionTypesStep](https://docs.medusajs.com/references/medusa-workflows/steps/createShippingOptionTypesStep/index.html.md)
+- [deleteShippingOptionTypesStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteShippingOptionTypesStep/index.html.md)
 - [listShippingOptionsForContextStep](https://docs.medusajs.com/references/medusa-workflows/steps/listShippingOptionsForContextStep/index.html.md)
-- [updateShippingOptionTypesStep](https://docs.medusajs.com/references/core_flows/Shipping_Options/Steps_Shipping_Options/functions/core_flows.Shipping_Options.Steps_Shipping_Options.updateShippingOptionTypesStep/index.html.md)
+- [updateShippingOptionTypesStep](https://docs.medusajs.com/references/medusa-workflows/steps/updateShippingOptionTypesStep/index.html.md)
 - [deleteShippingProfilesStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteShippingProfilesStep/index.html.md)
 - [createStockLocations](https://docs.medusajs.com/references/medusa-workflows/steps/createStockLocations/index.html.md)
 - [deleteStockLocationsStep](https://docs.medusajs.com/references/medusa-workflows/steps/deleteStockLocationsStep/index.html.md)

www/apps/resources/app/troubleshooting/_sections/common-installation-errors/pnpm.mdx

@@ -0,0 +1,23 @@
+If you use `pnpm` as a package manager in your Medusa application, you might face errors about missing packages. For example:
+
+```bash
+can't resolve @medusajs/dashboard
+```
+
+## Why This Error Occurred
+
+Medusa doesn't officially support `pnpm` as a package manager, which may lead to unexpected errors, including issues with package resolution.
+
+---
+
+## How to Fix it
+
+To resolve this error and other potential errors, consider switching to `yarn` as your package manager.
+
+If you still want to use `pnpm`, you must manually install the following packages in your project:
+
+```bash
+pnpm add @medusajs/dashboard @medusajs/icons @meduasjs/types @medusajs/draft-order @medusajs/ui
+```
+
+Make sure to also update these packages whenever you update your Medusa application.

www/apps/resources/app/troubleshooting/pnpm/page.mdx

@@ -0,0 +1,9 @@
+import PnpmSection from "../_sections/common-installation-errors/pnpm.mdx"
+
+export const metadata = {
+  title: `Errors with pnpm`,
+}
+
+# {metadata.title}
+
+<PnpmSection />

www/apps/resources/generated/edit-dates.mjs

@@ -6570,5 +6570,6 @@ export const generatedEditDates = {
   "app/integrations/guides/payload/page.mdx": "2025-08-21T05:24:11.537Z",
   "references/js_sdk/admin/Client/methods/js_sdk.admin.Client.getToken/page.mdx": "2025-08-14T12:59:55.678Z",
   "app/commerce-modules/order/draft-orders/page.mdx": "2025-08-26T09:21:49.780Z",
-  "app/troubleshooting/scheduled-job-not-running/page.mdx": "2025-08-29T11:32:54.117Z"
+  "app/troubleshooting/scheduled-job-not-running/page.mdx": "2025-08-29T11:32:54.117Z",
+  "app/troubleshooting/pnpm/page.mdx": "2025-08-29T12:21:24.692Z"
 }

www/apps/resources/generated/files-map.mjs

@@ -1423,6 +1423,10 @@ export const filesMap = [
     "filePath": "/www/apps/resources/app/troubleshooting/payment/page.mdx",
     "pathname": "/troubleshooting/payment"
   },
+  {
+    "filePath": "/www/apps/resources/app/troubleshooting/pnpm/page.mdx",
+    "pathname": "/troubleshooting/pnpm"
+  },
   {
     "filePath": "/www/apps/resources/app/troubleshooting/query/expression-type-error/page.mdx",
     "pathname": "/troubleshooting/query/expression-type-error"

www/apps/resources/generated/generated-troubleshooting-sidebar.mjs

@@ -43,6 +43,14 @@ const generatedgeneratedTroubleshootingSidebarSidebar = {
           "path": "/troubleshooting/general-errors",
           "title": "General Errors",
           "children": []
+        },
+        {
+          "loaded": true,
+          "isPathHref": true,
+          "type": "link",
+          "path": "/troubleshooting/pnpm",
+          "title": "pnpm Errors",
+          "children": []
         }
       ]
     },

www/apps/resources/sidebars/troubleshooting.mjs

@@ -28,6 +28,11 @@ export const troubleshootingSidebar = [
         path: "/troubleshooting/general-errors",
         title: "General Errors",
       },
+      {
+        type: "link",
+        path: "/troubleshooting/pnpm",
+        title: "pnpm Errors",
+      },
     ],
   },
   {