From 50c141737827a64d56d5916952ade2f2d89f9476 Mon Sep 17 00:00:00 2001 From: Shahed Nasser Date: Fri, 3 Oct 2025 13:09:01 +0300 Subject: [PATCH] docs: improve troubleshooting guide for pnpm (#13673) * docs: improve troubleshooting guide for pnpm * added pnpm link to installation guide --- .../app/learn/fundamentals/admin/tips/page.mdx | 14 ++++++++++++++ www/apps/book/app/learn/installation/page.mdx | 3 ++- www/apps/book/generated/edit-dates.mjs | 2 +- www/apps/book/public/llms-full.txt | 14 ++++++++++++++ .../common-installation-errors/pnpm.mdx | 16 +++++++++++++++- 5 files changed, 46 insertions(+), 3 deletions(-) diff --git a/www/apps/book/app/learn/fundamentals/admin/tips/page.mdx b/www/apps/book/app/learn/fundamentals/admin/tips/page.mdx index 15b2f0564e..1481e91c39 100644 --- a/www/apps/book/app/learn/fundamentals/admin/tips/page.mdx +++ b/www/apps/book/app/learn/fundamentals/admin/tips/page.mdx @@ -161,6 +161,20 @@ You can also send requests to custom routes, as explained in the [JS SDK referen You may need to retrieve data before your component is rendered, or you may need to pass some initial data to your component to be used while data is being fetched. In those cases, you can use a [route loader](../routing/page.mdx). +### Troubleshooting + +#### No QueryClient set + +If you're using `pnpm` as a package manager in your Medusa application, you might face the following error when you try to access the admin dashboard: + +```bash +No QueryClient set, use QueryClientProvider to set one +``` + +This is a known issue when using `pnpm`. To fix it, you need to install the `@tanstack/react-query` package manually. Make sure to install the same version installed in [@medusajs/dashboard](https://github.com/medusajs/medusa/blob/d58462c9c91a3e335d03f758438e109caad1f839/packages/admin/dashboard/package.json#L54). + +Learn more in the [Errors with pnpm](!resources!/troubleshooting/pnpm) troubleshooting guide. + --- ## Global Variables in Admin Customizations diff --git a/www/apps/book/app/learn/installation/page.mdx b/www/apps/book/app/learn/installation/page.mdx index bdac4712c8..cf70fabf8e 100644 --- a/www/apps/book/app/learn/installation/page.mdx +++ b/www/apps/book/app/learn/installation/page.mdx @@ -71,7 +71,8 @@ If you ran into an error during your installation, refer to the following troubl 1. [create-medusa-app troubleshooting guides](!resources!/troubleshooting/create-medusa-app-errors). 2. [CORS errors](!resources!/troubleshooting/cors-errors). -3. [All troubleshooting guides](!resources!/troubleshooting). +3. [Errors with pnpm](!resources!/troubleshooting/pnpm). +4. [All troubleshooting guides](!resources!/troubleshooting). If you can't find your error reported anywhere, please open a [GitHub issue](https://github.com/medusajs/medusa/issues/new/choose). diff --git a/www/apps/book/generated/edit-dates.mjs b/www/apps/book/generated/edit-dates.mjs index ed326e35de..25b717f641 100644 --- a/www/apps/book/generated/edit-dates.mjs +++ b/www/apps/book/generated/edit-dates.mjs @@ -43,7 +43,7 @@ export const generatedEditDates = { "app/learn/fundamentals/scheduled-jobs/execution-number/page.mdx": "2025-07-25T15:54:56.135Z", "app/learn/fundamentals/api-routes/parameters/page.mdx": "2025-09-15T15:47:08.409Z", "app/learn/fundamentals/api-routes/http-methods/page.mdx": "2025-07-25T15:12:29.347Z", - "app/learn/fundamentals/admin/tips/page.mdx": "2025-08-20T11:37:12.855Z", + "app/learn/fundamentals/admin/tips/page.mdx": "2025-10-03T08:35:15.022Z", "app/learn/fundamentals/api-routes/cors/page.mdx": "2025-03-11T08:54:26.281Z", "app/learn/fundamentals/admin/ui-routes/page.mdx": "2025-07-25T06:58:26.149Z", "app/learn/fundamentals/api-routes/middlewares/page.mdx": "2025-07-18T15:20:25.735Z", diff --git a/www/apps/book/public/llms-full.txt b/www/apps/book/public/llms-full.txt index 8997bfe69d..7cf6c63336 100644 --- a/www/apps/book/public/llms-full.txt +++ b/www/apps/book/public/llms-full.txt @@ -6992,6 +6992,20 @@ You can also send requests to custom routes, as explained in the [JS SDK referen You may need to retrieve data before your component is rendered, or you may need to pass some initial data to your component to be used while data is being fetched. In those cases, you can use a [route loader](https://docs.medusajs.com/learn/fundamentals/admin/routing/index.html.md). +### Troubleshooting + +#### No QueryClient set + +If you're using `pnpm` as a package manager in your Medusa application, you might face the following error when you try to access the admin dashboard: + +```bash +No QueryClient set, use QueryClientProvider to set one +``` + +This is a known issue when using `pnpm`. To fix it, you need to install the `@tanstack/react-query` package manually. Make sure to install the same version installed in [@medusajs/dashboard](https://github.com/medusajs/medusa/blob/d58462c9c91a3e335d03f758438e109caad1f839/packages/admin/dashboard/package.json#L54). + +Learn more in the [Errors with pnpm](https://docs.medusajs.com/resources/troubleshooting/pnpm/index.html.md) troubleshooting guide. + *** ## Global Variables in Admin Customizations diff --git a/www/apps/resources/app/troubleshooting/_sections/common-installation-errors/pnpm.mdx b/www/apps/resources/app/troubleshooting/_sections/common-installation-errors/pnpm.mdx index 75d1eefed8..e606778dc2 100644 --- a/www/apps/resources/app/troubleshooting/_sections/common-installation-errors/pnpm.mdx +++ b/www/apps/resources/app/troubleshooting/_sections/common-installation-errors/pnpm.mdx @@ -4,10 +4,18 @@ If you use `pnpm` as a package manager in your Medusa application, you might fac can't resolve @medusajs/dashboard ``` +You may also receive an error related to Tanstack Query: + +```bash +No QueryClient set, use QueryClientProvider to set one +``` + ## 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. +For Tanstack Query, the error occurs because the package is required by `@medusajs/dashboard`, but `pnpm` does not automatically install it as a dependency of that package. + --- ## How to Fix it @@ -17,7 +25,13 @@ To resolve this error and other potential errors, consider switching to `yarn` a 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 +pnpm add @medusajs/dashboard @medusajs/icons @medusajs/types @medusajs/draft-order @medusajs/ui ``` Make sure to also update these packages whenever you update your Medusa application. + +For the Tanstack Query error, you must also install it manually. It must be the same version installed in [@medusajs/dashboard](https://github.com/medusajs/medusa/blob/d58462c9c91a3e335d03f758438e109caad1f839/packages/admin/dashboard/package.json#L54): + +```bash +pnpm add @tanstack/react-query@{version} +``` \ No newline at end of file