From b1c63c5476c8b7d081f494440d0e197b199054e1 Mon Sep 17 00:00:00 2001 From: Shahed Nasser Date: Tue, 6 Jun 2023 15:18:23 +0300 Subject: [PATCH] docs: added troubleshooting component (#4255) --- docs/content/admin/quickstart.mdx | 15 ++++ .../cli/{reference.md => reference.mdx} | 10 ++- docs/content/create-medusa-app.mdx | 28 ++++++- ...g-on-vercel.md => deploying-on-vercel.mdx} | 40 +++++++--- .../deployments/server/deploying-on-qovery.md | 2 +- .../server/deploying-on-railway.md | 2 +- ...vercel.md => deploying-next-on-vercel.mdx} | 30 +++++-- docs/content/development/backend/install.mdx | 45 ++++++++--- .../backend/prepare-environment.mdx | 7 +- .../{add-middleware.md => add-middleware.mdx} | 25 +++++- docs/content/development/endpoints/create.md | 2 +- ...-in-user.md => example-logged-in-user.mdx} | 25 +++++- .../entities/migrations/overview.mdx | 2 +- .../development/feature-flags/toggle.md | 2 +- .../development/file-service/overview.mdx | 2 +- .../fundamentals/dependency-injection.md | 4 +- .../create-notification-provider.md | 2 +- .../development/notification/overview.mdx | 2 +- docs/content/development/plugins/create.md | 2 +- docs/content/development/search/overview.mdx | 2 +- .../{create-service.md => create-service.mdx} | 16 ++++ .../{extend-service.md => extend-service.mdx} | 18 ++++- .../backend/add-fulfillment-provider.md | 4 +- .../backend/add-payment-provider.md | 4 +- .../modules/carts-and-checkout/payment.md | 2 +- .../modules/carts-and-checkout/shipping.md | 4 +- .../taxes/storefront/manual-calculation.md | 4 +- docs/content/plugins/analytics/segment.md | 4 +- docs/content/plugins/cms/contentful/index.md | 2 +- docs/content/plugins/cms/strapi.md | 2 +- .../plugins/file-service/{s3.md => s3.mdx} | 28 +++++-- .../plugins/notifications/mailchimp.md | 2 +- .../plugins/notifications/twilio-sms.md | 2 +- .../plugins/payment/{stripe.md => stripe.mdx} | 20 ++++- .../starters/nextjs-medusa-starter.mdx | 24 ++++-- .../awilix-resolution-error.md | 78 ------------------- .../awilix-resolution-error.mdx | 25 ++++++ .../_custom-registration.md | 27 +++++++ .../_fresh-installation.md | 5 ++ .../_service-lifetime.md | 34 ++++++++ .../cli-installation-errors.mdx | 50 +++--------- .../_permission-errors.md | 3 + .../_powershell-error.md | 7 ++ .../_reusable-section.mdx | 21 +++++ .../cli-installation-errors/_yarn-error.mdx | 31 ++++++++ .../common-installation-errors.mdx | 30 ++----- .../_module-x-error.mdx | 25 ++++++ docs/content/troubleshooting/cors-issues.md | 6 +- .../create-medusa-app-errors.md | 16 ---- .../create-medusa-app-errors.mdx | 16 ++++ .../create-medusa-app-errors/_other-errors.md | 1 + .../create-medusa-app-errors/_typeerror.md | 8 ++ .../troubleshooting/database-error.mdx | 16 ++++ .../database-errors/_connection-error.md | 10 +++ .../_sasl.md} | 4 +- .../troubleshooting/documentation-error.md | 4 +- .../troubleshooting/errors-after-update.md | 4 +- .../missing-payment-providers.md | 7 +- docs/content/troubleshooting/redis-events.md | 4 +- docs/content/troubleshooting/s3-acl-error.md | 6 +- .../troubleshooting/signing-in-to-admin.md | 6 +- docs/content/upgrade-guides/admin/1-0-0.md | 2 +- docs/styles/docs/Acronyms.yml | 8 +- .../src/components/Troubleshooting/index.tsx | 25 ++++++ 64 files changed, 607 insertions(+), 257 deletions(-) rename docs/content/cli/{reference.md => reference.mdx} (95%) rename docs/content/deployments/admin/{deploying-on-vercel.md => deploying-on-vercel.mdx} (83%) rename docs/content/deployments/storefront/{deploying-next-on-vercel.md => deploying-next-on-vercel.mdx} (85%) rename docs/content/development/endpoints/{add-middleware.md => add-middleware.mdx} (90%) rename docs/content/development/endpoints/{example-logged-in-user.md => example-logged-in-user.mdx} (87%) rename docs/content/development/services/{create-service.md => create-service.mdx} (93%) rename docs/content/development/services/{extend-service.md => extend-service.mdx} (87%) rename docs/content/plugins/file-service/{s3.md => s3.mdx} (88%) rename docs/content/plugins/payment/{stripe.md => stripe.mdx} (94%) delete mode 100644 docs/content/troubleshooting/awilix-resolution-error.md create mode 100644 docs/content/troubleshooting/awilix-resolution-error.mdx create mode 100644 docs/content/troubleshooting/awilix-resolution-error/_custom-registration.md create mode 100644 docs/content/troubleshooting/awilix-resolution-error/_fresh-installation.md create mode 100644 docs/content/troubleshooting/awilix-resolution-error/_service-lifetime.md create mode 100644 docs/content/troubleshooting/cli-installation-errors/_permission-errors.md create mode 100644 docs/content/troubleshooting/cli-installation-errors/_powershell-error.md create mode 100644 docs/content/troubleshooting/cli-installation-errors/_reusable-section.mdx create mode 100644 docs/content/troubleshooting/cli-installation-errors/_yarn-error.mdx create mode 100644 docs/content/troubleshooting/common-installation-errors/_module-x-error.mdx delete mode 100644 docs/content/troubleshooting/create-medusa-app-errors.md create mode 100644 docs/content/troubleshooting/create-medusa-app-errors.mdx create mode 100644 docs/content/troubleshooting/create-medusa-app-errors/_other-errors.md create mode 100644 docs/content/troubleshooting/create-medusa-app-errors/_typeerror.md create mode 100644 docs/content/troubleshooting/database-error.mdx create mode 100644 docs/content/troubleshooting/database-errors/_connection-error.md rename docs/content/troubleshooting/{database-error.md => database-errors/_sasl.md} (68%) create mode 100644 www/docs/src/components/Troubleshooting/index.tsx diff --git a/docs/content/admin/quickstart.mdx b/docs/content/admin/quickstart.mdx index e6a828e977..29858c0e2a 100644 --- a/docs/content/admin/quickstart.mdx +++ b/docs/content/admin/quickstart.mdx @@ -4,6 +4,8 @@ addHowToData: true --- import Feedback from '@site/src/components/Feedback'; +import Troubleshooting from '@site/src/components/Troubleshooting' +import AdminLoginSection from '../troubleshooting/signing-in-to-admin.md' # Admin Dashboard Quickstart @@ -263,3 +265,16 @@ You can add the following options to the `medusa-admin dev` command: The admin dashboard provides a lot of ecommerce features including managing Return Merchandise Authorization (RMA) flows, store settings, products, orders, and much more. You can learn more about the admin dashboard and its features in the [User Guide](../user-guide.mdx). + +--- + +## Troubleshooting Installation + + + }, + ]} +/> diff --git a/docs/content/cli/reference.md b/docs/content/cli/reference.mdx similarity index 95% rename from docs/content/cli/reference.md rename to docs/content/cli/reference.mdx index 8336da2e34..e5141807ac 100644 --- a/docs/content/cli/reference.md +++ b/docs/content/cli/reference.mdx @@ -2,6 +2,8 @@ description: 'Learn how to install the Medusa CLI Tool. Medusa CLI Tool can be used to perform actions such as create a new Medusa backend, run migrations, create a new admin user, and more.' --- +import TroubleshootingSection from "../troubleshooting/cli-installation-errors/_reusable-section.mdx" + # CLI Reference This document serves as a reference to the Medusa CLI tool including how to install it and what commands are available. @@ -24,7 +26,7 @@ npm install @medusajs/medusa-cli -g :::note -If you run into any errors while installing the CLI tool, check out the [troubleshooting guide](../troubleshooting/cli-installation-errors.mdx). +If you run into any errors while installing the CLI tool, check out the [troubleshooting section](#troubleshooting-installation). ::: @@ -36,6 +38,12 @@ medusa --help --- +## Troubleshooting Installation + + + +--- + ## Common Options The following options can be used with all available commands. diff --git a/docs/content/create-medusa-app.mdx b/docs/content/create-medusa-app.mdx index 0e36fc020c..dc901413c6 100644 --- a/docs/content/create-medusa-app.mdx +++ b/docs/content/create-medusa-app.mdx @@ -5,7 +5,12 @@ addHowToData: true import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -import Feedback from '@site/src/components/Feedback'; +import Feedback from '@site/src/components/Feedback' +import Troubleshooting from '@site/src/components/Troubleshooting' +import TypeErrorSection from "./troubleshooting/create-medusa-app-errors/_typeerror.md" +import OtherErrorsSection from "./troubleshooting/create-medusa-app-errors/_other-errors.md" +import ConnectionErrorSection from './troubleshooting/database-errors/_connection-error.md' +import FreshInstallationSection from './troubleshooting/awilix-resolution-error/_fresh-installation.md' # Install Medusa with create-medusa-app @@ -224,7 +229,26 @@ If you open your storefront now in your browser on `localhost:8000`, everything ## Troubleshooting -If you run into any errors during the installation, please refer to [this troubleshooting guide](./troubleshooting/create-medusa-app-errors.md) for a potential help. + + }, + { + title: "Error: connect ECONNREFUSED ::1:5432", + content: + }, + { + title: 'AwilixResolutionError: Could Not Resolve X', + content: + }, + { + title: "Other Errors", + content: + }, + ]} +/> --- diff --git a/docs/content/deployments/admin/deploying-on-vercel.md b/docs/content/deployments/admin/deploying-on-vercel.mdx similarity index 83% rename from docs/content/deployments/admin/deploying-on-vercel.md rename to docs/content/deployments/admin/deploying-on-vercel.mdx index c13e7f41f7..af25acf008 100644 --- a/docs/content/deployments/admin/deploying-on-vercel.md +++ b/docs/content/deployments/admin/deploying-on-vercel.mdx @@ -3,6 +3,9 @@ description: 'Learn step-by-step.' addHowToData: true --- +import Troubleshooting from '@site/src/components/Troubleshooting' +import CorsErrorSection from '../../troubleshooting/cors-issues.md' + # Deploy Admin to Vercel In this document, you’ll learn how to deploy the admin dashboard to Vercel. @@ -57,7 +60,7 @@ git init git remote add origin ``` -Where `` is the URL you just copied. +Where `` is the URL you just copied. Then, add, commit, and push the changes into the repository: @@ -125,14 +128,14 @@ This section covers how to deploy the admin, either using the Vercel website or This section explains how to deploy the admin using the Vercel website: -1. Open the [Vercel dashboard](https://vercel.com/dashboard) after logging in. +1. Open the [Vercel dashboard](https://vercel.com/dashboard) after logging in. 2. Click on the “Add New…” button next to the search bar. 3. Choose Project from the dropdown. 4. In the new page that opens, find the Git repository that holds your Medusa backend and click on the Import button. If you haven’t connected your Vercel account to any Git provider, you must do that first. 5. In the Configure Project form: 1. Set the Framework Preset to Vite. 2. Open the Build and Output Settings collapsible, and set the Build Command to `yarn build:admin` and the Output Directory to `build`. If you’ve configured the admin to use a different output directory, then change it to that directory. - 3. Open the Environment Variables collapsible, and add an environment variable with the name `MEDUSA_BACKEND_URL` with the value being the URL to your deployed Medusa backend. + 3. Open the Environment Variables collapsible, and add an environment variable with the name `MEDUSA_BACKEND_URL` with the value being the URL to your deployed Medusa backend. 4. You can optionally edit the Project Name. 6. Once you’re done, click on the “Deploy” button. @@ -140,13 +143,13 @@ This will start the deployment of the admin. Once it’s done, you’ll be redir :::note -At this point, when you visit the admin, you will face errors related to Cross-Origin Resource Sharing (CORS) while using the admin. Before you start using the admin, follow along the [Configure CORS on the Medusa Backend](#step-6-configure-cors-on-the-medusa-backend) section. +At this point, when you visit the admin, you will face errors related to Cross-Origin Resource Sharing (CORS) while using the admin. Before you start using the admin, follow along the [Configure CORS on the Medusa Backend](#step-6-configure-cors-on-the-medusa-backend) section. ::: ### Option 2: Using Vercel’s CLI Tool -This section explains how to deploy the admin using the Vercel CLI tool. You should have the CLI tool installed first, as explained in [Vercel’s documentation](https://vercel.com/docs/cli). +This section explains how to deploy the admin using the Vercel CLI tool. You should have the CLI tool installed first, as explained in [Vercel’s documentation](https://vercel.com/docs/cli). In the directory of your Medusa backend, run the following command to deploy your admin: @@ -154,13 +157,13 @@ In the directory of your Medusa backend, run the following command to deploy you vercel --build-env MEDUSA_BACKEND_URL= ``` -Where `` is the URL of your deployed Medusa backend. +Where `` is the URL of your deployed Medusa backend. You’ll then be asked to log in if you haven’t already, and to choose the scope to deploy your project to. You can also decide to link the admin to an existing project, or change the project’s name. -When asked, ”In which directory is your code located?”, keep the default `./` and just press Enter. +When asked, ”In which directory is your code located?”, keep the default `./` and just press Enter. -The project setup will then start. When asked if you want to modify the settings, answer `y`. You’ll then be asked a series of questions: +The project setup will then start. When asked if you want to modify the settings, answer `y`. You’ll then be asked a series of questions: 1. “Which settings would you like to overwrite”: select Build Command and Output Directory using the space bar, then press Enter. 2. “What's your **Build Command**?”: enter `yarn build:admin`. @@ -170,7 +173,7 @@ After that, it will take a couple of minutes for the deployment to finish. The l :::note -At this point, when you visit the admin, you will face errors related to Cross-Origin Resource Sharing (CORS) while using the admin. Before you start using the admin, follow along the [Configure CORS on the Medusa Backend](#step-6-configure-cors-on-the-medusa-backend) section. +At this point, when you visit the admin, you will face errors related to Cross-Origin Resource Sharing (CORS) while using the admin. Before you start using the admin, follow along the [Configure CORS on the Medusa Backend](#step-6-configure-cors-on-the-medusa-backend) section. ::: @@ -178,11 +181,11 @@ At this point, when you visit the admin, you will face errors related to Cross-O ## Step 6: Configure CORS on the Medusa Backend -To send requests to the Medusa backend from the admin dashboard, you must set the `ADMIN_CORS` environment variable on your backend to the admin’s URL. +To send requests to the Medusa backend from the admin dashboard, you must set the `ADMIN_CORS` environment variable on your backend to the admin’s URL. :::note -If you want to set a custom domain to your admin dashboard on Vercel, make sure to do it before this step. You can refer to this guide on [Vercel’s documentation](https://vercel.com/docs/concepts/projects/domains/add-a-domain). +If you want to set a custom domain to your admin dashboard on Vercel, make sure to do it before this step. You can refer to this guide on [Vercel’s documentation](https://vercel.com/docs/concepts/projects/domains/add-a-domain). ::: @@ -192,6 +195,19 @@ On your Medusa backend, add the following environment variable: ADMIN_CORS= ``` -Where `` is the URL of your admin dashboard that you just deployed. +Where `` is the URL of your admin dashboard that you just deployed. Then, restart your Medusa backend. Once the backend is running again, you can use your admin dashboard. + +--- + +## Troubleshooting + + + }, + ]} +/> \ No newline at end of file diff --git a/docs/content/deployments/server/deploying-on-qovery.md b/docs/content/deployments/server/deploying-on-qovery.md index df58aad6fa..18e3b0cf38 100644 --- a/docs/content/deployments/server/deploying-on-qovery.md +++ b/docs/content/deployments/server/deploying-on-qovery.md @@ -516,7 +516,7 @@ qovery shell You’ll be asked to either confirm the existing context or choose a new context. -After choosing your Medusa app in the context, you should be able to execute any command in the directory of your Medusa backend. For example, you can run the [`user` command using Medusa’s CLI tool to create a new user](../../cli/reference.md#user): +After choosing your Medusa app in the context, you should be able to execute any command in the directory of your Medusa backend. For example, you can run the [`user` command using Medusa’s CLI tool to create a new user](../../cli/reference.mdx#user): ```bash npm install @medusajs/medusa-cli -g diff --git a/docs/content/deployments/server/deploying-on-railway.md b/docs/content/deployments/server/deploying-on-railway.md index 8527e46f9f..bff8324ec4 100644 --- a/docs/content/deployments/server/deploying-on-railway.md +++ b/docs/content/deployments/server/deploying-on-railway.md @@ -221,7 +221,7 @@ If you run into any issues or a problem with your deployed backend, you can chec To run commands on your backend, you can use [Railway’s CLI tool to run a local shell and execute commands](https://docs.railway.app/develop/cli#local-shell). -For example, you can run commands on the backend to seed the database or create a new user using [Medusa’s CLI tool](../../cli/reference.md). +For example, you can run commands on the backend to seed the database or create a new user using [Medusa’s CLI tool](../../cli/reference.mdx). --- diff --git a/docs/content/deployments/storefront/deploying-next-on-vercel.md b/docs/content/deployments/storefront/deploying-next-on-vercel.mdx similarity index 85% rename from docs/content/deployments/storefront/deploying-next-on-vercel.md rename to docs/content/deployments/storefront/deploying-next-on-vercel.mdx index a1fa0a9340..0d7309eff7 100644 --- a/docs/content/deployments/storefront/deploying-next-on-vercel.md +++ b/docs/content/deployments/storefront/deploying-next-on-vercel.mdx @@ -3,6 +3,9 @@ description: 'Learn step-by-step.' addHowToData: true --- +import Troubleshooting from '@site/src/components/Troubleshooting' +import CorsErrorSection from '../../troubleshooting/cors-issues.md' + # Deploy Next.js Storefront on Vercel In this document, you’ll learn how to deploy the Next.js Storefront on Vercel. @@ -20,7 +23,7 @@ Alternatively, you can directly deploy the Next.js storefront to Vercel with thi It is assumed you already have installed the Next.js storefront locally. If not, please follow along with [this guide](../../starters/nextjs-medusa-starter.mdx) instead. -It’s also assumed you already have the Medusa backend deployed, which the Next.js storefront interacts with. If not, you can check out one of the [deployment documentation related to the Medusa backend](../server/index.mdx). +It’s also assumed you already have the Medusa backend deployed, which the Next.js storefront interacts with. If not, you can check out one of the [deployment documentation related to the Medusa backend](../server/index.mdx). ### Required Accounts @@ -66,7 +69,7 @@ git init git remote add origin ``` -Where `` is the URL you just copied. +Where `` is the URL you just copied. Then, add, commit, and push the changes into the repository: @@ -101,7 +104,7 @@ This will start the deployment of the storefront. Once it’s done, you’ll be :::note -At this point, when you visit the storefront, you will face errors related to Cross-Origin Resource Sharing (CORS) while using the storefront. Before you start using the storefront, follow along the [Configure CORS on the Medusa Backend](#step-3-configure-cors-on-the-medusa-backend) section. +At this point, when you visit the storefront, you will face errors related to Cross-Origin Resource Sharing (CORS) while using the storefront. Before you start using the storefront, follow along the [Configure CORS on the Medusa Backend](#step-3-configure-cors-on-the-medusa-backend) section. ::: @@ -127,7 +130,7 @@ It will take a couple of minutes for the deployment to finish. The link to the s :::note -At this point, when you visit the storefront, you will face errors related to Cross-Origin Resource Sharing (CORS) while using the storefront. Before you start using the storefront, follow along the [Configure CORS on the Medusa Backend](#step-3-configure-cors-on-the-medusa-backend) section. +At this point, when you visit the storefront, you will face errors related to Cross-Origin Resource Sharing (CORS) while using the storefront. Before you start using the storefront, follow along the [Configure CORS on the Medusa Backend](#step-3-configure-cors-on-the-medusa-backend) section. ::: @@ -135,11 +138,11 @@ At this point, when you visit the storefront, you will face errors related to Cr ## Step 3: Configure CORS on the Medusa Backend -To send requests to the Medusa backend from the Next.js storefront, you must set the `STORE_CORS` environment variable on your backend to the Next.js storefront’s URL. +To send requests to the Medusa backend from the Next.js storefront, you must set the `STORE_CORS` environment variable on your backend to the Next.js storefront’s URL. :::tip -If you want to set a custom domain to your Next.js storefront website on Vercel, make sure to do it before this step. You can refer to this guide on [Vercel’s documentation](https://vercel.com/docs/concepts/projects/domains/add-a-domain). +If you want to set a custom domain to your Next.js storefront website on Vercel, make sure to do it before this step. You can refer to this guide on [Vercel’s documentation](https://vercel.com/docs/concepts/projects/domains/add-a-domain). ::: @@ -149,6 +152,19 @@ On your Medusa backend, add the following environment variable: STORE_CORS= ``` -Where `` is the URL of your Next.js storefront that you just deployed. +Where `` is the URL of your Next.js storefront that you just deployed. Then, restart your Medusa backend. Once the backend is running again, you can use your Next.js storefront. + +--- + +## Troubleshooting + + + }, + ]} +/> \ No newline at end of file diff --git a/docs/content/development/backend/install.mdx b/docs/content/development/backend/install.mdx index 961f8cc40b..d505e226b0 100644 --- a/docs/content/development/backend/install.mdx +++ b/docs/content/development/backend/install.mdx @@ -6,6 +6,10 @@ addHowToData: true import Feedback from '@site/src/components/Feedback'; import DocCardList from '@theme/DocCardList'; import Icons from '@theme/Icon'; +import Troubleshooting from '@site/src/components/Troubleshooting' +import SaslSection from '../../troubleshooting/database-errors/_sasl.md' +import ConnectionErrorSection from '../../troubleshooting/database-errors/_connection-error.md' +import FreshInstallationSection from '../../troubleshooting/awilix-resolution-error/_fresh-installation.md' # Install Medusa Backend @@ -68,6 +72,12 @@ Make sure your PostgreSQL server is running before you run the Medusa backend. medusa develop ``` +After these three steps and in only a couple of minutes, you now have a complete commerce engine running locally. You can test it out by sending a request using a tool like Postman or through the command line: + +```bash noReport +curl localhost:9000/store/products +``` + -### Seed Data +--- + +## Troubleshooting Installation + + + }, + { + title: 'Error: connect ECONNREFUSED ::1:5432', + content: + }, + { + title: 'AwilixResolutionError: Could Not Resolve X', + content: + }, + ]} +/> + +--- + +## Seed Data For better testing, you can add demo data to your Medusa backend by running the seed command in your Medusa backend directory: @@ -83,15 +116,9 @@ For better testing, you can add demo data to your Medusa backend by running the medusa seed --seed-file=data/seed.json ``` -### Test the Backend +--- -After these three steps and in only a couple of minutes, you now have a complete commerce engine running locally. You can test it out by sending a request using a tool like Postman or through the command line: - -```bash noReport -curl localhost:9000/store/products -``` - -### Health Route +## Health Route You can access `/health` to get health status of your backend. diff --git a/docs/content/development/backend/prepare-environment.mdx b/docs/content/development/backend/prepare-environment.mdx index 6dd0c18cd4..e3c58665f8 100644 --- a/docs/content/development/backend/prepare-environment.mdx +++ b/docs/content/development/backend/prepare-environment.mdx @@ -4,6 +4,7 @@ description: 'Learn how to prepare your development environment while using Medu import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; +import MedusaCliTroubleshootingSection from '../../troubleshooting/cli-installation-errors/_reusable-section.mdx' # Prepare Development Environment @@ -136,11 +137,9 @@ You can check that Medusa was installed by running the following command: medusa -v ``` -:::note +#### Troubleshooting Installation -If you run into any errors while installing the CLI tool, check out the [troubleshooting guide](../../troubleshooting/cli-installation-errors.mdx). - -::: + ### PostgreSQL diff --git a/docs/content/development/endpoints/add-middleware.md b/docs/content/development/endpoints/add-middleware.mdx similarity index 90% rename from docs/content/development/endpoints/add-middleware.md rename to docs/content/development/endpoints/add-middleware.mdx index da7ffd6e7b..7db4bf11d0 100644 --- a/docs/content/development/endpoints/add-middleware.md +++ b/docs/content/development/endpoints/add-middleware.mdx @@ -3,6 +3,10 @@ description: 'Learn how to add a middleware in Medusa. A middleware is a functio addHowToData: true --- +import Troubleshooting from '@site/src/components/Troubleshooting' +import ServiceLifetimeSection from '../../troubleshooting/awilix-resolution-error/_service-lifetime.md' +import CustomRegistrationSection from '../../troubleshooting/awilix-resolution-error/_custom-registration.md' + # Middlewares In this document, you’ll learn how to add a middleware to an existing or custom route in Medusa. @@ -103,7 +107,7 @@ In some cases, you may need to register a resource to use within your commerce a :::tip -If you want to register a logged-in user and access it in your resources, you can check out [this example guide](./example-logged-in-user.md). +If you want to register a logged-in user and access it in your resources, you can check out [this example guide](./example-logged-in-user.mdx). ::: @@ -151,7 +155,7 @@ Notice that you have to wrap your usage of the new resource in a try-catch block ### Note About Services Lifetime -If you want to access new registrations in the dependency container within a service, you must set the lifetime of the service either to `Lifetime.SCOPED` or `Lifetime.TRANSIENT`. Services that have a `Lifetime.SINGLETON` lifetime can't access new registrations since they're resolved and cached in the root dependency container beforehand. You can learn more in the [Create Services documentation](../services/create-service.md#service-life-time). +If you want to access new registrations in the dependency container within a service, you must set the lifetime of the service either to `Lifetime.SCOPED` or `Lifetime.TRANSIENT`. Services that have a `Lifetime.SINGLETON` lifetime can't access new registrations since they're resolved and cached in the root dependency container beforehand. You can learn more in the [Create Services documentation](../services/create-service.mdx#service-life-time). For custom services, no additional action is required as the default lifetime is `Lifetime.SCOPED`. However, if you extend a core service, you must change the lifetime since the default lifetime for core services is `Lifetime.SINGLETON`. @@ -189,6 +193,23 @@ export default ProductService --- +## Troubleshooting + + + }, + { + title: 'AwilixResolutionError: Could Not Resolve X (Custom Registration)', + content: + } + ]} +/> + +--- + ## See Also - [Store API reference](/api/store) diff --git a/docs/content/development/endpoints/create.md b/docs/content/development/endpoints/create.md index 7fb539624d..dd9df4ee2b 100644 --- a/docs/content/development/endpoints/create.md +++ b/docs/content/development/endpoints/create.md @@ -42,7 +42,7 @@ This exports a function that returns an Express router. The function receives tw ### Defining Multiple Routes or Middlewares -Instead of returning an Express router in the function, you can return an array of routes and [middlewares](./add-middleware.md). +Instead of returning an Express router in the function, you can return an array of routes and [middlewares](./add-middleware.mdx). For example: diff --git a/docs/content/development/endpoints/example-logged-in-user.md b/docs/content/development/endpoints/example-logged-in-user.mdx similarity index 87% rename from docs/content/development/endpoints/example-logged-in-user.md rename to docs/content/development/endpoints/example-logged-in-user.mdx index 2313d52740..3f4247f88f 100644 --- a/docs/content/development/endpoints/example-logged-in-user.md +++ b/docs/content/development/endpoints/example-logged-in-user.mdx @@ -3,13 +3,17 @@ description: 'In this document, you’ll see an example of how you can use middl addHowToData: true --- +import Troubleshooting from '@site/src/components/Troubleshooting' +import ServiceLifetimeSection from '../../troubleshooting/awilix-resolution-error/_service-lifetime.md' +import CustomRegistrationSection from '../../troubleshooting/awilix-resolution-error/_custom-registration.md' + # Example: Access Logged-In User In this document, you’ll see an example of how you can use middlewares and endpoints to register the logged-in user in the dependency container of your commerce application. You can then access the logged-in user in other resources, such as services. This guide showcases how to register the logged-in admin user, but you can apply the same steps if you want to register the current customer. -This documentation does not explain the basics of [middlewares](./add-middleware.md) and [endpoints](./create.md). You can refer to their respective guides for more details about each. +This documentation does not explain the basics of [middlewares](./add-middleware.mdx) and [endpoints](./create.md). You can refer to their respective guides for more details about each. ## Step 1: Create the Middleware @@ -178,7 +182,7 @@ class ProductService extends MedusaProductService { export default ProductService ``` -You can learn more about the importance of changing the service lifetime in the [Middlewares documentation](./add-middleware.md#note-about-services-lifetime). +You can learn more about the importance of changing the service lifetime in the [Middlewares documentation](./add-middleware.mdx#note-about-services-lifetime). --- @@ -197,3 +201,20 @@ npx @medusajs/medusa-cli develop ``` If you try accessing the endpoints you added the middleware to, you should see your implementation working as expected. + +--- + +## Troubleshooting + + + }, + { + title: 'AwilixResolutionError: Could Not Resolve X (Custom Registration)', + content: + } + ]} +/> diff --git a/docs/content/development/entities/migrations/overview.mdx b/docs/content/development/entities/migrations/overview.mdx index 03ec1e1def..332718748c 100644 --- a/docs/content/development/entities/migrations/overview.mdx +++ b/docs/content/development/entities/migrations/overview.mdx @@ -59,7 +59,7 @@ npx @medusajs/medusa-cli@latest migrations revert ### Other Migrations Commands -You can learn about migration commands available in the Medusa CLI tool by referring to the [Medusa CLI reference](../../../cli/reference.md#migrations) +You can learn about migration commands available in the Medusa CLI tool by referring to the [Medusa CLI reference](../../../cli/reference.mdx#migrations) --- diff --git a/docs/content/development/feature-flags/toggle.md b/docs/content/development/feature-flags/toggle.md index 003f18bcd0..6d2413ca9c 100644 --- a/docs/content/development/feature-flags/toggle.md +++ b/docs/content/development/feature-flags/toggle.md @@ -80,4 +80,4 @@ Once you disable a feature flag, all endpoints, entities, services, or other rel If you had the feature flag previously enabled, and you want to disable this feature flag completely, you might need to revert the migrations you ran when you enabled it. -You can follow [this documentation to learn how to revert the last migration you ran](../../cli/reference.md#migrations). \ No newline at end of file +You can follow [this documentation to learn how to revert the last migration you ran](../../cli/reference.mdx#migrations). \ No newline at end of file diff --git a/docs/content/development/file-service/overview.mdx b/docs/content/development/file-service/overview.mdx index bba01c9ffa..df9eee0848 100644 --- a/docs/content/development/file-service/overview.mdx +++ b/docs/content/development/file-service/overview.mdx @@ -13,7 +13,7 @@ In this document, you’ll learn what a file service is in Medusa. A file service defines how files are stored in the Medusa Backend. Those files include products’ images and files used to import or export data. -Medusa Backend includes a default file service that acts as a placeholder, but does not actually perform any storage functionalities. So, you must either install one of the [existing file-service plugins](../../plugins/file-service/index.mdx), such as [MinIO](../../plugins/file-service/minio.md) or [S3](../../plugins/file-service/s3.md), or create your own file service if you want to utilize storage functionalities. +Medusa Backend includes a default file service that acts as a placeholder, but does not actually perform any storage functionalities. So, you must either install one of the [existing file-service plugins](../../plugins/file-service/index.mdx), such as [MinIO](../../plugins/file-service/minio.md) or [S3](../../plugins/file-service/s3.mdx), or create your own file service if you want to utilize storage functionalities. A file service is a TypeScript or JavaScript class that extends the `AbstractFileService` class from the core `@medusajs/medusa` package. By extending this class, the file service must implement the necessary methods that take care of general upload and download functionalities. The Medusa Backend then uses these methods when necessary, for example, when a product image is uploaded. diff --git a/docs/content/development/fundamentals/dependency-injection.md b/docs/content/development/fundamentals/dependency-injection.md index 5adc648345..a0c67856ed 100644 --- a/docs/content/development/fundamentals/dependency-injection.md +++ b/docs/content/development/fundamentals/dependency-injection.md @@ -38,7 +38,7 @@ The Medusa backend scans the core Medusa package, plugins, and your files in the :::tip -The Lifetime column indicates the lifetime of a service. Other resources that aren't services don't have a lifetime, which is indicated with the `-` in the column. You can learn about what a lifetime is in the [Create a Service](../services/create-service.md) documentation. +The Lifetime column indicates the lifetime of a service. Other resources that aren't services don't have a lifetime, which is indicated with the `-` in the column. You can learn about what a lifetime is in the [Create a Service](../services/create-service.mdx) documentation. ::: @@ -731,5 +731,5 @@ class OrderSubscriber { ## See Also -- [Create services](../services/create-service.md) +- [Create services](../services/create-service.mdx) - [Create subscribers](../events/create-subscriber.md) diff --git a/docs/content/development/notification/create-notification-provider.md b/docs/content/development/notification/create-notification-provider.md index 57a47b17ba..89071d74a5 100644 --- a/docs/content/development/notification/create-notification-provider.md +++ b/docs/content/development/notification/create-notification-provider.md @@ -67,7 +67,7 @@ Notification Providers must extend `NotificationService` from `medusa-interfa :::info -Following the naming convention of Services, the name of the file should be the slug name of the Notification Provider, and the name of the class should be the camel case name of the Notification Provider suffixed with “Service”. In the example above, the name of the file should be `email-sender.js`. You can learn more in the [service documentation](../services/create-service.md). +Following the naming convention of Services, the name of the file should be the slug name of the Notification Provider, and the name of the class should be the camel case name of the Notification Provider suffixed with “Service”. In the example above, the name of the file should be `email-sender.js`. You can learn more in the [service documentation](../services/create-service.mdx). ::: diff --git a/docs/content/development/notification/overview.mdx b/docs/content/development/notification/overview.mdx index 3e20f64c8c..d3f1bfe8e9 100644 --- a/docs/content/development/notification/overview.mdx +++ b/docs/content/development/notification/overview.mdx @@ -25,7 +25,7 @@ An example of a notification provider is SendGrid. When an order is placed, the ### How Notification Provider is Created -A Notification Provider is essentially a Medusa [Service](../services/create-service.md) with a unique identifier, and it extends the [`NotificationService`](../../references/services/classes/NotificationService.md) provided by the `medusa-interfaces` package. It can be created as part of a [Plugin](../plugins/overview.mdx), or it can be created just as a Service file in your Medusa backend. +A Notification Provider is essentially a Medusa [Service](../services/create-service.mdx) with a unique identifier, and it extends the [`NotificationService`](../../references/services/classes/NotificationService.md) provided by the `medusa-interfaces` package. It can be created as part of a [Plugin](../plugins/overview.mdx), or it can be created just as a Service file in your Medusa backend. As a developer, you mainly work with the Notification Provider when integrating a third-party service that handles notifications in Medusa. diff --git a/docs/content/development/plugins/create.md b/docs/content/development/plugins/create.md index 2c3aa3b3c0..1174b70277 100644 --- a/docs/content/development/plugins/create.md +++ b/docs/content/development/plugins/create.md @@ -136,7 +136,7 @@ It was previously required to output your files into the root of the plugin's di This guide doesn't cover how to create different files and components. If you’re interested in learning how to do that, you can check out these guides: - How to [create endpoints](../endpoints/create.md) -- How to [create a service](../services/create-service.md) +- How to [create a service](../services/create-service.mdx) - How to [create a subscriber](../events/create-subscriber.md) - How to [create an entity](../entities/create.md) - How to [create a migration](../entities/migrations/create.md) diff --git a/docs/content/development/search/overview.mdx b/docs/content/development/search/overview.mdx index 592c779b1a..592f070078 100644 --- a/docs/content/development/search/overview.mdx +++ b/docs/content/development/search/overview.mdx @@ -15,7 +15,7 @@ A search service is used to manage search indices of searchable items, such as p A search service is a service class that is defined in a TypeScript or JavaScript file, which is created in the `src/services` directory of your Medusa backend codebase or plugin. The class must extend the `AbstractSearchService` class imported from the `@medusajs/utils` package. -Using the [dependency container and injection](../fundamentals/dependency-injection.md), the Medusa backend will then use and resolve the search service within the backend’s search operations, such as when the [Search Product](/api/store#tag/Products/operation/PostProductsSearch) endpoint is used. You can also [resolve the service](../services/create-service.md#use-a-service) within your resources to trigger the search where necessary. +Using the [dependency container and injection](../fundamentals/dependency-injection.md), the Medusa backend will then use and resolve the search service within the backend’s search operations, such as when the [Search Product](/api/store#tag/Products/operation/PostProductsSearch) endpoint is used. You can also [resolve the service](../services/create-service.mdx#use-a-service) within your resources to trigger the search where necessary. Medusa provides official plugins that you can install and use in your Medusa backend. Check out available search plugins [here](../../plugins/search/index.mdx). diff --git a/docs/content/development/services/create-service.md b/docs/content/development/services/create-service.mdx similarity index 93% rename from docs/content/development/services/create-service.md rename to docs/content/development/services/create-service.mdx index bd0ed12ccf..f85b9871b4 100644 --- a/docs/content/development/services/create-service.md +++ b/docs/content/development/services/create-service.mdx @@ -3,6 +3,9 @@ description: 'Learn how to create a service in Medusa. This guide also includes addHowToData: true --- +import Troubleshooting from '@site/src/components/Troubleshooting' +import ServiceLifetimeSection from '../../troubleshooting/awilix-resolution-error/_service-lifetime.md' + # How to Create a Service In this document, you’ll learn how you can create a [Service](./overview.mdx) and use it across your Medusa backend just like any of the core services. @@ -143,6 +146,19 @@ class MySubscriber { --- +## Troubleshooting + + + } + ]} +/> + +--- + ## See Also - [Create a Plugin](../plugins/create.md) diff --git a/docs/content/development/services/extend-service.md b/docs/content/development/services/extend-service.mdx similarity index 87% rename from docs/content/development/services/extend-service.md rename to docs/content/development/services/extend-service.mdx index ccaf7a93d2..660f43a0f3 100644 --- a/docs/content/development/services/extend-service.md +++ b/docs/content/development/services/extend-service.mdx @@ -3,6 +3,9 @@ description: 'Learn how to create a service in Medusa. This guide also includes addHowToData: true --- +import Troubleshooting from '@site/src/components/Troubleshooting' +import ServiceLifetimeSection from '../../troubleshooting/awilix-resolution-error/_service-lifetime.md' + # How to Extend a Service In this document, you’ll learn how to extend a core service in Medusa. @@ -65,7 +68,7 @@ class ProductService extends MedusaProductService { export default ProductService ``` -You can learn more details about the service lifetime and other considerations when creating a service in the [Create Service documentation](./create-service.md). +You can learn more details about the service lifetime and other considerations when creating a service in the [Create Service documentation](./create-service.mdx). --- @@ -84,3 +87,16 @@ npx @medusajs/medusa-cli develop ``` You should see the customizations you made in effect. + +--- + +## Troubleshooting + + + } + ]} +/> diff --git a/docs/content/modules/carts-and-checkout/backend/add-fulfillment-provider.md b/docs/content/modules/carts-and-checkout/backend/add-fulfillment-provider.md index e570ef8470..4558bd4a5d 100644 --- a/docs/content/modules/carts-and-checkout/backend/add-fulfillment-provider.md +++ b/docs/content/modules/carts-and-checkout/backend/add-fulfillment-provider.md @@ -13,7 +13,7 @@ A fulfillment provider is the shipping provider used to fulfill orders and deliv By default, a Medusa Backend has a `manual` fulfillment provider which has minimal implementation. It allows you to accept orders and fulfill them manually. However, you can integrate any fulfillment provider into Medusa, and your fulfillment provider can interact with third-party shipping providers. -Adding a fulfillment provider is as simple as creating one [service](../../../development/services/create-service.md) file in `src/services`. A fulfillment provider is essentially a service that extends the `FulfillmentService`. It requires implementing 4 methods: +Adding a fulfillment provider is as simple as creating one [service](../../../development/services/create-service.mdx) file in `src/services`. A fulfillment provider is essentially a service that extends the `FulfillmentService`. It requires implementing 4 methods: 1. `getFulfillmentOptions`: used to retrieve available fulfillment options provided by this fulfillment provider. 2. `validateOption`: used to validate the shipping option when it’s being created by the admin. @@ -44,7 +44,7 @@ Fulfillment provider services must extend the `FulfillmentService` class importe :::note -Following the naming convention of Services, the name of the file should be the slug name of the fulfillment provider, and the name of the class should be the camel case name of the fulfillment provider suffixed with “Service”. You can learn more in the [service documentation](../../../development/services/create-service.md). +Following the naming convention of Services, the name of the file should be the slug name of the fulfillment provider, and the name of the class should be the camel case name of the fulfillment provider suffixed with “Service”. You can learn more in the [service documentation](../../../development/services/create-service.mdx). ::: diff --git a/docs/content/modules/carts-and-checkout/backend/add-payment-provider.md b/docs/content/modules/carts-and-checkout/backend/add-payment-provider.md index bee3a274d2..a5b407295a 100644 --- a/docs/content/modules/carts-and-checkout/backend/add-payment-provider.md +++ b/docs/content/modules/carts-and-checkout/backend/add-payment-provider.md @@ -19,7 +19,7 @@ A Payment Processor is the payment method used to authorize, capture, and refund By default, Medusa has a [manual payment provider](https://github.com/medusajs/medusa/tree/master/packages/medusa-payment-manual) that has minimal implementation. It can be synonymous with a Cash on Delivery payment method. It allows store operators to manage the payment themselves but still keep track of its different stages on Medusa. -Adding a Payment Processor is as simple as creating a [service](../../../development/services/create-service.md) file in `src/services`. A Payment Processor is essentially a service that extends `AbstractPaymentProcessor` from the core Medusa package `@medusajs/medusa`. +Adding a Payment Processor is as simple as creating a [service](../../../development/services/create-service.mdx) file in `src/services`. A Payment Processor is essentially a service that extends `AbstractPaymentProcessor` from the core Medusa package `@medusajs/medusa`. Payment Processor Services must have a static property `identifier`. It's the name that will be used to install and refer to the Payment Processor in the Medusa backend. @@ -141,7 +141,7 @@ Payment Processors must extend `AbstractPaymentProcessor` from the core Medusa p :::tip -Following the naming convention of Services, the name of the file should be the slug name of the Payment Processor, and the name of the class should be the camel case name of the Payment Processors suffixed with “Service”. In the example above, the name of the file should be `my-payment.ts`. You can learn more in the [service documentation](../../../development/services/create-service.md). +Following the naming convention of Services, the name of the file should be the slug name of the Payment Processor, and the name of the class should be the camel case name of the Payment Processors suffixed with “Service”. In the example above, the name of the file should be `my-payment.ts`. You can learn more in the [service documentation](../../../development/services/create-service.mdx). ::: diff --git a/docs/content/modules/carts-and-checkout/payment.md b/docs/content/modules/carts-and-checkout/payment.md index 1313fc0b9d..f09641370e 100644 --- a/docs/content/modules/carts-and-checkout/payment.md +++ b/docs/content/modules/carts-and-checkout/payment.md @@ -42,7 +42,7 @@ The manual payment plugin is still considered a payment provider since it does n ### How Payment Processor is Created -A Payment Processor is essentially a Medusa [service](../../development/services/create-service.md) with a unique identifier, and it extends the `AbstractPaymentProcessor` from the core Medusa package `@medusajs/medusa`. You can create it as part of a [plugin](../../development/plugins/overview.mdx), or just as a service file in your Medusa backend. +A Payment Processor is essentially a Medusa [service](../../development/services/create-service.mdx) with a unique identifier, and it extends the `AbstractPaymentProcessor` from the core Medusa package `@medusajs/medusa`. You can create it as part of a [plugin](../../development/plugins/overview.mdx), or just as a service file in your Medusa backend. As a developer, you will mainly work with the Payment Processor when integrating a payment method in Medusa. diff --git a/docs/content/modules/carts-and-checkout/shipping.md b/docs/content/modules/carts-and-checkout/shipping.md index bb64b96451..845adb8508 100644 --- a/docs/content/modules/carts-and-checkout/shipping.md +++ b/docs/content/modules/carts-and-checkout/shipping.md @@ -18,7 +18,7 @@ It’s also constructed to support multiple regions, provide different shipment ## Summary -- **Fulfillment Provider:** Fulfillment providers are plugins or [Services](../../development/services/create-service.md) used to ship the products to your customers, whether physically or virtually. An example of a fulfillment provider would be FedEx. +- **Fulfillment Provider:** Fulfillment providers are plugins or [Services](../../development/services/create-service.mdx) used to ship the products to your customers, whether physically or virtually. An example of a fulfillment provider would be FedEx. - **Shipping Profiles:** created by the admin. They are used to group products that should be shipped in a different manner than the default. Shipping profiles can have multiple shipping options. - **Shipping Options:** created by the admin and belong to a shipping profile. They are specific to certain regions and can have cart conditions. They use an underlying fulfillment provider. Once a customer checks out, they can choose the shipping option that’s available and most relevant to them. - **Shipping Method:** created when the customer chooses a shipping option on checkout. The shipping method is basically a copy of the shipping option, but with values specific to the customer and the cart it’s associated with. When the order is placed, the shipping method will then be associated with the order and fulfilled based on the integration with the fulfillment provider. @@ -39,7 +39,7 @@ Fulfillment Providers can also be related to a custom way of handling fulfillmen ### How Fulfillment Provider is Created -A Fulfillment Provider is essentially a Medusa [Service](../../development/services/create-service.md) with a unique identifier, and it extends the `FulfillmentService` provided by the `medusa-interfaces` package. It can be created as part of a [plugin](../../development/plugins/overview.mdx), or it can be created just as a Service file in your Medusa backend. +A Fulfillment Provider is essentially a Medusa [Service](../../development/services/create-service.mdx) with a unique identifier, and it extends the `FulfillmentService` provided by the `medusa-interfaces` package. It can be created as part of a [plugin](../../development/plugins/overview.mdx), or it can be created just as a Service file in your Medusa backend. As a developer, you will mainly work with the Fulfillment Provider when integrating a fulfillment method in Medusa. diff --git a/docs/content/modules/taxes/storefront/manual-calculation.md b/docs/content/modules/taxes/storefront/manual-calculation.md index 461fd04c8c..0f743e6660 100644 --- a/docs/content/modules/taxes/storefront/manual-calculation.md +++ b/docs/content/modules/taxes/storefront/manual-calculation.md @@ -45,7 +45,7 @@ cartService.retrieve( :::tip -You can learn how to [retrieve and use services](../../../development/services/create-service.md#using-your-custom-service) in this documentation. +You can learn how to [retrieve and use services](../../../development/services/create-service.mdx#using-your-custom-service) in this documentation. ::: @@ -89,6 +89,6 @@ const itemTotals = await totalsService :::tip -You can learn how to [retrieve and use services](../../../development/services/create-service.md#using-your-custom-service) in this documentation. +You can learn how to [retrieve and use services](../../../development/services/create-service.mdx#using-your-custom-service) in this documentation. ::: \ No newline at end of file diff --git a/docs/content/plugins/analytics/segment.md b/docs/content/plugins/analytics/segment.md index e99096a4d9..585679ff06 100644 --- a/docs/content/plugins/analytics/segment.md +++ b/docs/content/plugins/analytics/segment.md @@ -185,7 +185,7 @@ You resolve the `SegmentService` using dependency injection. Then, when the `cus :::info -Services can be resolved and used in Subscribers, endpoints, and other Services. Learn [how to resolve services in the Services documentation](../../development/services/create-service.md#using-your-custom-service). +Services can be resolved and used in Subscribers, endpoints, and other Services. Learn [how to resolve services in the Services documentation](../../development/services/create-service.mdx#using-your-custom-service). ::: @@ -205,7 +205,7 @@ After adding the above subscriber, run your backend again if it isn’t running ## See Also -- [Services Overview](../../development/services/create-service.md) +- [Services Overview](../../development/services/create-service.mdx) - [Subscribers Overview](../../development/events/create-subscriber.md) - [Events Reference](../../development/events/events-list.md) - [Deploy the Medusa backend](../../deployments/server/index.mdx) diff --git a/docs/content/plugins/cms/contentful/index.md b/docs/content/plugins/cms/contentful/index.md index b88f2ce490..aa19c51fa7 100644 --- a/docs/content/plugins/cms/contentful/index.md +++ b/docs/content/plugins/cms/contentful/index.md @@ -27,7 +27,7 @@ By integrating Contentful to Medusa, you can benefit from powerful features in y - Redis. You can follow [their documentation to learn how to install it](https://redis.io/docs/getting-started/installation/). - Git’s CLI tool. You can follow [this documentation to learn how to install it for your operating system](../../../development/backend/prepare-environment.mdx#git). - Gatsby’s CLI tool. You can follow [this documentation to install it](https://www.gatsbyjs.com/docs/reference/gatsby-cli/#how-to-use-gatsby-cli). -- Medusa’s CLI tool. You can follow [this documentation to install it](../../../cli/reference.md#how-to-install-cli-tool). +- Medusa’s CLI tool. You can follow [this documentation to install it](../../../cli/reference.mdx#how-to-install-cli-tool). --- diff --git a/docs/content/plugins/cms/strapi.md b/docs/content/plugins/cms/strapi.md index e4eeb6775d..e7e929e627 100644 --- a/docs/content/plugins/cms/strapi.md +++ b/docs/content/plugins/cms/strapi.md @@ -25,7 +25,7 @@ By integrating Strapi to Medusa, you can benefit from powerful features in your ### Medusa CLI -[Medusa’s CLI tool](../../cli/reference.md#how-to-install-cli-tool) is required to set up a new Medusa backend. +[Medusa’s CLI tool](../../cli/reference.mdx#how-to-install-cli-tool) is required to set up a new Medusa backend. ### Redis diff --git a/docs/content/plugins/file-service/s3.md b/docs/content/plugins/file-service/s3.mdx similarity index 88% rename from docs/content/plugins/file-service/s3.md rename to docs/content/plugins/file-service/s3.mdx index 7108e5bbfb..5cb5e07900 100644 --- a/docs/content/plugins/file-service/s3.md +++ b/docs/content/plugins/file-service/s3.mdx @@ -3,6 +3,9 @@ description: 'Learn how to integrate the S3 plugin with the Medusa backend. Lear addHowToData: true --- +import Troubleshooting from '@site/src/components/Troubleshooting' +import AclErrorSection from '../../troubleshooting/s3-acl-error.md' + # S3 In this document, you’ll learn how to install the [S3 plugin](https://github.com/medusajs/medusa/tree/master/packages/medusa-file-s3) on your Medusa backend and use it for storage. @@ -19,7 +22,7 @@ Medusa provides three different options to handle your file storage. This docume ### Medusa Backend -A Medusa backend is required to be set up before following along with this document. You can follow the [quickstart guide](../../development/backend/install.mdx) to get started in minutes. +A Medusa backend is required to be set up before following along with this document. You can follow the [quickstart guide](../../development/backend/install.mdx) to get started in minutes. ### Required Accounts @@ -166,7 +169,7 @@ Make sure to define `S3_REGION`, `S3_ACCESS_KEY_ID`, and `S3_SECRET_ACCESS_KEY` :::caution -If you have multiple storage plugins configured, the last plugin declared in the `medusa-config.js` file will be used. +If you have multiple storage plugins configured, the last plugin declared in the `medusa-config.js` file will be used. ::: @@ -194,11 +197,11 @@ You can also check that the image was uploaded on the S3 bucket’s page. ## Next.js Storefront Configuration -If you’re using a [Next.js](../../starters/nextjs-medusa-starter.mdx) storefront, you need to add an additional configuration that adds the S3 bucket domain name into the configured images’ domain names. This is because all URLs of product images will be from the S3 bucket. +If you’re using a [Next.js](../../starters/nextjs-medusa-starter.mdx) storefront, you need to add an additional configuration that adds the S3 bucket domain name into the configured images’ domain names. This is because all URLs of product images will be from the S3 bucket. -If this configuration is not added, you’ll receive the error ["next/image Un-configured Host”](https://nextjs.org/docs/messages/next-image-unconfigured-host). +If this configuration is not added, you’ll receive the error ["next/image Un-configured Host”](https://nextjs.org/docs/messages/next-image-unconfigured-host). -In `next.config.js` add the following option in the exported object: +In `next.config.js` add the following option in the exported object: ```jsx title=next.config.js const { withStoreConfig } = require("./store-config") @@ -220,8 +223,21 @@ Where `` is the name of the S3 bucket you’re using. --- +## Troubleshooting + + + } + ]} +/> + +--- + ## See Also -- Check out [more plugins](../overview.mdx) you can add to your store. +- Check out [more plugins](../overview.mdx) you can add to your store. - [Deploy the Medusa backend](../../deployments/server/index.mdx) - Install the [Next.js](../../starters/nextjs-medusa-starter.mdx) starter storefront. diff --git a/docs/content/plugins/notifications/mailchimp.md b/docs/content/plugins/notifications/mailchimp.md index a5e8d55098..0466a98a19 100644 --- a/docs/content/plugins/notifications/mailchimp.md +++ b/docs/content/plugins/notifications/mailchimp.md @@ -134,7 +134,7 @@ mailchimpService.subscribeNewsletter( :::tip -You can learn more about how you can use services in your endpoints, services, and subscribers in the [Services documentation](../../development/services/create-service.md#using-your-custom-service). +You can learn more about how you can use services in your endpoints, services, and subscribers in the [Services documentation](../../development/services/create-service.mdx#using-your-custom-service). ::: diff --git a/docs/content/plugins/notifications/twilio-sms.md b/docs/content/plugins/notifications/twilio-sms.md index a72a63827a..0dc3d80fe9 100644 --- a/docs/content/plugins/notifications/twilio-sms.md +++ b/docs/content/plugins/notifications/twilio-sms.md @@ -73,7 +73,7 @@ const plugins = [ ## Example Usage of the Plugin -This plugin adds the service `twilioSmsService` to your Medusa backend. To send SMS using it, all you have to do is resolve it in your file as explained in the [Services](../../development/services/create-service.md#using-your-custom-service) documentation. +This plugin adds the service `twilioSmsService` to your Medusa backend. To send SMS using it, all you have to do is resolve it in your file as explained in the [Services](../../development/services/create-service.mdx#using-your-custom-service) documentation. In this example, you’ll create a subscriber that listens to the `order.placed` event and sends an SMS to the customer to confirm their order. diff --git a/docs/content/plugins/payment/stripe.md b/docs/content/plugins/payment/stripe.mdx similarity index 94% rename from docs/content/plugins/payment/stripe.md rename to docs/content/plugins/payment/stripe.mdx index 86b430aa24..7130d8d703 100644 --- a/docs/content/plugins/payment/stripe.md +++ b/docs/content/plugins/payment/stripe.mdx @@ -3,6 +3,9 @@ description: 'Learn how to integrate Stripe with the Medusa backend. Learn how t addHowToData: true --- +import Troubleshooting from '@site/src/components/Troubleshooting' +import MissingPaymentProvider from '../../troubleshooting/missing-payment-providers.md' + # Stripe This document guides you through setting up Stripe payments in your Medusa backend, admin, and storefront using the [Stripe Plugin](https://github.com/medusajs/medusa/tree/master/packages/medusa-payment-stripe). @@ -19,9 +22,9 @@ You can also follow this video guide to learn how the setup works: ## Overview -[Stripe](https://stripe.com/) is a battle-tested and unified platform for transaction handling. Stripe supplies you with the technical components needed to handle transactions safely and all the analytical features necessary to gain insight into your sales. These features are also available in a safe test environment which allows for a concern-free development process. +[Stripe](https://stripe.com/) is a battle-tested and unified platform for transaction handling. Stripe supplies you with the technical components needed to handle transactions safely and all the analytical features necessary to gain insight into your sales. These features are also available in a safe test environment which allows for a concern-free development process. -Using the `medusa-payment-stripe` plugin, this guide shows you how to set up your Medusa project with Stripe as a payment processor. +Using the `medusa-payment-stripe` plugin, this guide shows you how to set up your Medusa project with Stripe as a payment processor. --- @@ -379,6 +382,19 @@ This plugin handles the following Stripe webhook events: --- +## Troubleshooting + + + } + ]} +/> + +--- + ## See Also - Check out [more plugins](../overview.mdx) you can add to your store. diff --git a/docs/content/starters/nextjs-medusa-starter.mdx b/docs/content/starters/nextjs-medusa-starter.mdx index c280c836f5..39569fc4a2 100644 --- a/docs/content/starters/nextjs-medusa-starter.mdx +++ b/docs/content/starters/nextjs-medusa-starter.mdx @@ -4,6 +4,9 @@ description: 'Learn how to install the Next.js starter storefront to use with Me import Feedback from '@site/src/components/Feedback'; import QueryNote from '@site/src/components/QueryNote'; +import Troubleshooting from '@site/src/components/Troubleshooting' +import ModuleXErrorSection from '../troubleshooting/common-installation-errors/_module-x-error.mdx' +import CorsErrorSection from '../troubleshooting/cors-issues.md' # Next.js Storefront Quickstart @@ -87,11 +90,22 @@ Your Next.js storefront is now running at `localhost:8000`! negativeQuestion="Please describe the issue you faced." /> -:::tip +--- -If you run into errors during the installation, check out [this troubleshooting guide](../troubleshooting/common-installation-errors.mdx). +## Troubleshooting Installation -::: + + }, + { + title: 'Resolve "Cannot find module X" Errors', + content: + }, + ]} +/> --- @@ -193,7 +207,7 @@ Then, restart the Next.js backend. You’ll be able to search through available ### Stripe Payment Integration -Stripe integration is supported by default. Make sure you have Stripe installed and enabled on your Medusa backend first. You can [follow this guide to learn how to install it](../plugins/payment/stripe.md). +Stripe integration is supported by default. Make sure you have Stripe installed and enabled on your Medusa backend first. You can [follow this guide to learn how to install it](../plugins/payment/stripe.mdx). Then, in your Next.js storefront, set the environment variable necessary for the Stripe integration: @@ -278,4 +292,4 @@ You can learn more about development with Next.js through [their documentation]( - [Storefront API reference](https://docs.medusajs.com/api/store) - [Install Medusa Admin](../admin/quickstart.mdx). -- [Install Stripe as a payment processor](../plugins/payment/stripe.md#add-to-nextjs-storefront) +- [Install Stripe as a payment processor](../plugins/payment/stripe.mdx#add-to-nextjs-storefront) diff --git a/docs/content/troubleshooting/awilix-resolution-error.md b/docs/content/troubleshooting/awilix-resolution-error.md deleted file mode 100644 index 561a3825c5..0000000000 --- a/docs/content/troubleshooting/awilix-resolution-error.md +++ /dev/null @@ -1,78 +0,0 @@ -# AwilixResolutionError: Could Not Resolve X - -This troubleshooting guide will help you figure out the different situations that can cause an `AwilixResolutionError`. - -## Option 1: Service Lifetime - -If you're registering a custom resource within a middleware, for example a logged-in user, then make sure that all services that are using it have their `LIFE_TIME` static property either set to `Lifetime.SCOPED` or `Lifetime.TRANSIENT`. This mainly applies for services in the core Medusa package, as, by default, their lifetime is `Lifetime.SINGLETON`. - -For example: - -```ts -import { Lifetime } from "awilix" -import { - ProductService as MedusaProductService, -} from "@medusajs/medusa" - -// extending ProductService from the core -class ProductService extends MedusaProductService { - // The default life time for a core service is SINGLETON - static LIFE_TIME = Lifetime.SCOPED - - // ... -} - -export default ProductService -``` - -This may require you to extend a service as explained in [this documentation](../development/services/extend-service.md) if necessary. - -If you're unsure which service you need to change its `LIFE_TIME` property, it should be mentioned along with the `AwilixResolutionError` message. For example: - -```bash noCopy noReport -AwilixResolutionError: Could not resolve 'loggedInUser'. - -Resolution path: cartService -> productService -> loggedInUser -``` - -As shown in the resolution path, you must change the `LIFE_TIME` property of both `cartService` and `productService` to `Lifetime.SCOPED` or `Lifetime.TRANSIENT`. - -You can learn about the service lifetime in the [Create a Service documentation](../development/services/create-service.md). - -## Option 2: Using Try-Catch Block with Custom Registration - -When you register a custom resource using a middleware, make sure that when you use it in a service's constructor you wrap it in a try-catch block. This can cause an error when the Medusa backend first runs, especially if the service is used within a subscriber. Subscribers are built the first time the Medusa backend runs, meaning that their dependencies are registered at that point. Since your custom resource hasn't been registered at this point, it will cause an `AwilixResolutionError` when the backend tries to resolve it. - -For that reason, and to avoid other similar situations, make sure to always wrap your custom resources in a try-catch block when you use them inside the constructor of a service. For example: - - - -```ts -import { TransactionBaseService } from "@medusajs/medusa" - -class CustomService extends TransactionBaseService { - - constructor(container, options) { - super(...arguments) - - // use the registered resource. - try { - container.customResource - } catch (e) { - // avoid errors when the backend first loads - } - } -} - -export default CustomService -``` - -You can learn more about this in the [Middlewares documentation](../development/endpoints/add-middleware.md). - -## Option 3: Error on A Fresh Installation - -If you get the error on a fresh installation of the Medusa backend, or you haven't made any customizations that would cause this error, try to remove the `node_modules` directory, then run the following command in the root directory of the Medusa backend to re-install the dependencies: - -```bash npm2yarn -npm install -``` \ No newline at end of file diff --git a/docs/content/troubleshooting/awilix-resolution-error.mdx b/docs/content/troubleshooting/awilix-resolution-error.mdx new file mode 100644 index 0000000000..34c1203691 --- /dev/null +++ b/docs/content/troubleshooting/awilix-resolution-error.mdx @@ -0,0 +1,25 @@ +--- +title: 'AwilixResolutionError: Could Not Resolve X' +--- + +import ServiceLifetimeSection from './awilix-resolution-error/_service-lifetime.md' +import CustomRegistrationSection from './awilix-resolution-error/_custom-registration.md' +import FreshInstallationSection from './awilix-resolution-error/_fresh-installation.md' + +This troubleshooting guide will help you figure out the different situations that can cause an `AwilixResolutionError`. + +## Option 1: Service Lifetime + + + +--- + +## Option 2: Using Try-Catch Block with Custom Registration + + + +--- + +## Option 3: Error on A Fresh Installation + + diff --git a/docs/content/troubleshooting/awilix-resolution-error/_custom-registration.md b/docs/content/troubleshooting/awilix-resolution-error/_custom-registration.md new file mode 100644 index 0000000000..91f93fa190 --- /dev/null +++ b/docs/content/troubleshooting/awilix-resolution-error/_custom-registration.md @@ -0,0 +1,27 @@ +When you register a custom resource using a middleware, make sure that when you use it in a service's constructor you wrap it in a try-catch block. This can cause an error when the Medusa backend first runs, especially if the service is used within a subscriber. Subscribers are built the first time the Medusa backend runs, meaning that their dependencies are registered at that point. Since your custom resource hasn't been registered at this point, it will cause an `AwilixResolutionError` when the backend tries to resolve it. + +For that reason, and to avoid other similar situations, make sure to always wrap your custom resources in a try-catch block when you use them inside the constructor of a service. For example: + + + +```ts +import { TransactionBaseService } from "@medusajs/medusa" + +class CustomService extends TransactionBaseService { + + constructor(container, options) { + super(...arguments) + + // use the registered resource. + try { + container.customResource + } catch (e) { + // avoid errors when the backend first loads + } + } +} + +export default CustomService +``` + +You can learn more about this in the [Middlewares documentation](../../development/endpoints/add-middleware.mdx). diff --git a/docs/content/troubleshooting/awilix-resolution-error/_fresh-installation.md b/docs/content/troubleshooting/awilix-resolution-error/_fresh-installation.md new file mode 100644 index 0000000000..ff588eab38 --- /dev/null +++ b/docs/content/troubleshooting/awilix-resolution-error/_fresh-installation.md @@ -0,0 +1,5 @@ +If you get the error on a fresh installation of the Medusa backend, or you haven't made any customizations that would cause this error, try to remove the `node_modules` directory, then run the following command in the root directory of the Medusa backend to re-install the dependencies: + +```bash npm2yarn +npm install +``` diff --git a/docs/content/troubleshooting/awilix-resolution-error/_service-lifetime.md b/docs/content/troubleshooting/awilix-resolution-error/_service-lifetime.md new file mode 100644 index 0000000000..516d6edabc --- /dev/null +++ b/docs/content/troubleshooting/awilix-resolution-error/_service-lifetime.md @@ -0,0 +1,34 @@ +If you're registering a custom resource within a middleware, for example a logged-in user, then make sure that all services that are using it have their `LIFE_TIME` static property either set to `Lifetime.SCOPED` or `Lifetime.TRANSIENT`. This mainly applies for services in the core Medusa package, as, by default, their lifetime is `Lifetime.SINGLETON`. + +For example: + +```ts +import { Lifetime } from "awilix" +import { + ProductService as MedusaProductService, +} from "@medusajs/medusa" + +// extending ProductService from the core +class ProductService extends MedusaProductService { + // The default life time for a core service is SINGLETON + static LIFE_TIME = Lifetime.SCOPED + + // ... +} + +export default ProductService +``` + +This may require you to extend a service as explained in [this documentation](../../development/services/extend-service.mdx) if necessary. + +If you're unsure which service you need to change its `LIFE_TIME` property, it should be mentioned along with the `AwilixResolutionError` message. For example: + +```bash noCopy noReport +AwilixResolutionError: Could not resolve 'loggedInUser'. + +Resolution path: cartService -> productService -> loggedInUser +``` + +As shown in the resolution path, you must change the `LIFE_TIME` property of both `cartService` and `productService` to `Lifetime.SCOPED` or `Lifetime.TRANSIENT`. + +You can learn about the service lifetime in the [Create a Service documentation](../../development/services/create-service.mdx). \ No newline at end of file diff --git a/docs/content/troubleshooting/cli-installation-errors.mdx b/docs/content/troubleshooting/cli-installation-errors.mdx index c534eeec06..6bc331cc8c 100644 --- a/docs/content/troubleshooting/cli-installation-errors.mdx +++ b/docs/content/troubleshooting/cli-installation-errors.mdx @@ -1,15 +1,16 @@ -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; +--- +title: 'Resolve Errors Installing Medusa CLI' +--- -# Resolve Errors Installing Medusa CLI +import PermissionErrorsSection from './cli-installation-errors/_permission-errors.md' +import PowershellErrorSection from './cli-installation-errors/_powershell-error.md' +import YarnError from './cli-installation-errors/_yarn-error.mdx' In this document, you can find solutions to some common problems that occur when installing Medusa’s CLI Tool. ## NPM Error: EACCES Permissions Errors -If you install the Medusa CLI tool with NPM and get a permission error, NPM proposes as a solution either re-installing NPM with a node version manager (nvm), or manually setting npm’s default directory. - -You can check out more information in [NPM’s documentation](https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally). + --- @@ -19,13 +20,7 @@ You can check out more information in [NPM’s documentation](https://docs.npmjs -If you're using Powershell and you installed the CLI tool, but when you try to use it you get the error: - -```bash noReport -command not found: medusa -``` - -Try closing your Powershell window and opening a new one. + --- @@ -35,31 +30,4 @@ Try closing your Powershell window and opening a new one. -If you install the Medusa CLI tool with Yarn, then try to use the CLI tool but get the error: - -```bash noReport -command not found: medusa -``` - -You have to add Yarn’s install location to the PATH variable: - - - - -```bash -export PATH="$(yarn global bin):$PATH" -``` - - - - -```bash -# MAKE SURE TO INCLUDE %path% -setx path "%path%;c:\users\YOURUSERNAME\appdata\local\yarn\bin" -# YOURUSERNAME is your account username -``` - - - - -You can learn more in [Yarn’s documentation](https://classic.yarnpkg.com/en/docs/cli/global#adding-the-install-location-to-your-path). \ No newline at end of file + \ No newline at end of file diff --git a/docs/content/troubleshooting/cli-installation-errors/_permission-errors.md b/docs/content/troubleshooting/cli-installation-errors/_permission-errors.md new file mode 100644 index 0000000000..8593d5f4a7 --- /dev/null +++ b/docs/content/troubleshooting/cli-installation-errors/_permission-errors.md @@ -0,0 +1,3 @@ +If you install the Medusa CLI tool with NPM and get a permission error, NPM proposes as a solution either re-installing NPM with a node version manager (nvm), or manually setting npm’s default directory. + +You can check out more information in [NPM’s documentation](https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally). \ No newline at end of file diff --git a/docs/content/troubleshooting/cli-installation-errors/_powershell-error.md b/docs/content/troubleshooting/cli-installation-errors/_powershell-error.md new file mode 100644 index 0000000000..dd3ebb1e97 --- /dev/null +++ b/docs/content/troubleshooting/cli-installation-errors/_powershell-error.md @@ -0,0 +1,7 @@ +If you're using Powershell and you installed the CLI tool, but when you try to use it you get the error: + +```bash noReport +command not found: medusa +``` + +Try closing your Powershell window and opening a new one. diff --git a/docs/content/troubleshooting/cli-installation-errors/_reusable-section.mdx b/docs/content/troubleshooting/cli-installation-errors/_reusable-section.mdx new file mode 100644 index 0000000000..9888b2ddaf --- /dev/null +++ b/docs/content/troubleshooting/cli-installation-errors/_reusable-section.mdx @@ -0,0 +1,21 @@ +import Troubleshooting from '@site/src/components/Troubleshooting' +import PermissionErrorsSection from './_permission-errors.md' +import PowershellErrorSection from './_powershell-error.md' +import YarnErrorSection from './_yarn-error.mdx' + + + }, + { + title: "Powershell Error: command not found: medusa", + content: + }, + { + title: "Yarn Error: command not found: medusa", + content: + } + ]} +/> \ No newline at end of file diff --git a/docs/content/troubleshooting/cli-installation-errors/_yarn-error.mdx b/docs/content/troubleshooting/cli-installation-errors/_yarn-error.mdx new file mode 100644 index 0000000000..1cd72e521b --- /dev/null +++ b/docs/content/troubleshooting/cli-installation-errors/_yarn-error.mdx @@ -0,0 +1,31 @@ +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +If you install the Medusa CLI tool with Yarn, then try to use the CLI tool but get the error: + +```bash noReport +command not found: medusa +``` + +You have to add Yarn’s install location to the PATH variable: + + + + +```bash +export PATH="$(yarn global bin):$PATH" +``` + + + + +```bash +# MAKE SURE TO INCLUDE %path% +setx path "%path%;c:\users\YOURUSERNAME\appdata\local\yarn\bin" +# YOURUSERNAME is your account username +``` + + + + +You can learn more in [Yarn’s documentation](https://classic.yarnpkg.com/en/docs/cli/global#adding-the-install-location-to-your-path). \ No newline at end of file diff --git a/docs/content/troubleshooting/common-installation-errors.mdx b/docs/content/troubleshooting/common-installation-errors.mdx index 9a056e6657..069d6d1b0e 100644 --- a/docs/content/troubleshooting/common-installation-errors.mdx +++ b/docs/content/troubleshooting/common-installation-errors.mdx @@ -1,27 +1,9 @@ -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; +--- +title: 'General Errors' +--- -# Resolve "Cannot find module X" Errors +import ModuleXErrorSection from './common-installation-errors/_module-x-error.mdx' -This error can occur while installing one of the storefronts or the Medusa admin. There is no specific cause to this error. +## Resolve "Cannot find module X" Errors -One way to resolve it is by removing the `node_modules` directory in the project and re-installing the dependencies: - - - - -```bash -rm -rf node_modules -yarn install -``` - - - - -```bash -rd /s /q node_modules -yarn install -``` - - - \ No newline at end of file + \ No newline at end of file diff --git a/docs/content/troubleshooting/common-installation-errors/_module-x-error.mdx b/docs/content/troubleshooting/common-installation-errors/_module-x-error.mdx new file mode 100644 index 0000000000..b0040e6dbe --- /dev/null +++ b/docs/content/troubleshooting/common-installation-errors/_module-x-error.mdx @@ -0,0 +1,25 @@ +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +This error can occur while installing any of Medusa's projects (for example, Next.js storefront). There is no specific cause to this error. + +One way to resolve it is by removing the `node_modules` directory in the project and re-installing the dependencies: + + + + +```bash +rm -rf node_modules +yarn install +``` + + + + +```bash +rd /s /q node_modules +yarn install +``` + + + \ No newline at end of file diff --git a/docs/content/troubleshooting/cors-issues.md b/docs/content/troubleshooting/cors-issues.md index e1744ba86b..7fc6eabbb9 100644 --- a/docs/content/troubleshooting/cors-issues.md +++ b/docs/content/troubleshooting/cors-issues.md @@ -1,6 +1,8 @@ -# CORS issues +--- +title: 'CORS issues' +--- -If you are experiencing connection issues when trying to access your Medusa backend from a storefront, it is most likely due to Cross-Origin Resource Sharing (CORS) issues. +If you are experiencing connection issues when trying to access your Medusa backend from a storefront or the admin dashboard, it is most likely due to Cross-Origin Resource Sharing (CORS) issues. You might see a log in your browser console, that looks like this: diff --git a/docs/content/troubleshooting/create-medusa-app-errors.md b/docs/content/troubleshooting/create-medusa-app-errors.md deleted file mode 100644 index 92aec0e1bc..0000000000 --- a/docs/content/troubleshooting/create-medusa-app-errors.md +++ /dev/null @@ -1,16 +0,0 @@ -# Common Create-React-App Errors - -## TypeError: cmd is not a function - -This error typically occurs when you set up a Medusa project with `create-medusa-app` and try to run the Medusa backend. - -To resolve this issue, make sure you change into the `backend` directory of the Medusa project you created before trying to start the Medusa backend: - -```bash npm2yarn -cd backend -npx @medusajs/medusa-cli develop -``` - -## Other Errors - -If you ran into another error, please try to search through [our GitHub issues](https://github.com/medusajs/medusa/issues) to see if there's a solution for your issue. If not, please [create an issue on GitHub](https://github.com/medusajs/medusa/issues/new?assignees=olivermrbl&labels=status:+needs+triaging,+type:+bug&template=bug_report.md&title=) and our team will help you resolve it soon. diff --git a/docs/content/troubleshooting/create-medusa-app-errors.mdx b/docs/content/troubleshooting/create-medusa-app-errors.mdx new file mode 100644 index 0000000000..de128206e8 --- /dev/null +++ b/docs/content/troubleshooting/create-medusa-app-errors.mdx @@ -0,0 +1,16 @@ +--- +title: 'Common Create-React-App Errors' +--- + +import TypeError from './create-medusa-app-errors/_typeerror.md' +import OtherErrors from './create-medusa-app-errors/_other-errors.md' + +## TypeError: cmd is not a function + + + +--- + +## Other Errors + + \ No newline at end of file diff --git a/docs/content/troubleshooting/create-medusa-app-errors/_other-errors.md b/docs/content/troubleshooting/create-medusa-app-errors/_other-errors.md new file mode 100644 index 0000000000..e29896172e --- /dev/null +++ b/docs/content/troubleshooting/create-medusa-app-errors/_other-errors.md @@ -0,0 +1 @@ +If you ran into another error, please try to search through [our GitHub issues](https://github.com/medusajs/medusa/issues) to see if there's a solution for your issue. If not, please [create an issue on GitHub](https://github.com/medusajs/medusa/issues/new?assignees=olivermrbl&labels=status:+needs+triaging,+type:+bug&template=bug_report.md&title=) and our team will help you resolve it soon. diff --git a/docs/content/troubleshooting/create-medusa-app-errors/_typeerror.md b/docs/content/troubleshooting/create-medusa-app-errors/_typeerror.md new file mode 100644 index 0000000000..a9ff12fbdc --- /dev/null +++ b/docs/content/troubleshooting/create-medusa-app-errors/_typeerror.md @@ -0,0 +1,8 @@ +This error typically occurs when you set up a Medusa project with `create-medusa-app` and try to run the Medusa backend. + +To resolve this issue, make sure you change into the `backend` directory of the Medusa project you created before trying to start the Medusa backend: + +```bash npm2yarn +cd backend +npx @medusajs/medusa-cli develop +``` \ No newline at end of file diff --git a/docs/content/troubleshooting/database-error.mdx b/docs/content/troubleshooting/database-error.mdx new file mode 100644 index 0000000000..a797a33c1d --- /dev/null +++ b/docs/content/troubleshooting/database-error.mdx @@ -0,0 +1,16 @@ +--- +title: 'Database Errors' +--- + +import SaslSection from './database-errors/_sasl.md' +import ConnectionErrorSection from './database-errors/_connection-error.md' + +## Error: SASL: SCRAM-SERVER-FIRST-MESSAGE: Client password must be a string + + + +--- + +## Error: connect ECONNREFUSED ::1:5432 + + \ No newline at end of file diff --git a/docs/content/troubleshooting/database-errors/_connection-error.md b/docs/content/troubleshooting/database-errors/_connection-error.md new file mode 100644 index 0000000000..05cfde6826 --- /dev/null +++ b/docs/content/troubleshooting/database-errors/_connection-error.md @@ -0,0 +1,10 @@ +When you start your Medusa backend you may run into the following error: + +```bash +Error: connect ECONNREFUSED ::1:5432 +``` + +This error occurs because the backend couldn't connect to the PostgreSQL database. The issue could be one of the following: + +1. PostgreSQL server isn't running. Make sure it's always running while the Medusa backend is running. +2. The connection URL to your PostgreSQL database is incorrect. This could be because of incorrect credentials, port number, or connection URL format. The format should be `postgresql://[user[:password]@][host][:port][/dbname][?paramspec]`. Make sure that the connection URL format is correct, and the credentials passed in the URL are correct. diff --git a/docs/content/troubleshooting/database-error.md b/docs/content/troubleshooting/database-errors/_sasl.md similarity index 68% rename from docs/content/troubleshooting/database-error.md rename to docs/content/troubleshooting/database-errors/_sasl.md index 3ed8ee4e1d..0460c33c83 100644 --- a/docs/content/troubleshooting/database-error.md +++ b/docs/content/troubleshooting/database-errors/_sasl.md @@ -1,6 +1,4 @@ -# Error: SASL: SCRAM-SERVER-FIRST-MESSAGE: Client password must be a string - -You can get the following error while running `medusa new` or while running integration tests during [local development](../development/fundamentals/local-development.md): +You may get the following error while running `medusa new` or while running integration tests during [local development](../../development/fundamentals/local-development.md): ```bash Error: SASL: SCRAM-SERVER-FIRST-MESSAGE: client password must be a string diff --git a/docs/content/troubleshooting/documentation-error.md b/docs/content/troubleshooting/documentation-error.md index cc31b8e5e3..b04400323a 100644 --- a/docs/content/troubleshooting/documentation-error.md +++ b/docs/content/troubleshooting/documentation-error.md @@ -1,4 +1,6 @@ -# Troubleshooting Documentation Errors +--- +title: 'Troubleshooting Documentation Errors' +--- ## React Hook Errors diff --git a/docs/content/troubleshooting/errors-after-update.md b/docs/content/troubleshooting/errors-after-update.md index ee2ef31578..9137faddd5 100644 --- a/docs/content/troubleshooting/errors-after-update.md +++ b/docs/content/troubleshooting/errors-after-update.md @@ -1,4 +1,6 @@ -# Errors After Update +--- +title: 'Errors After Update' +--- If you run into errors after updating Medusa and its dependencies, it's highly recommended to check the [Upgrade Guides](../upgrade-guides/index.mdx) if there is a specific guide for your version. These guides include steps required to perform after upgrading Medusa. diff --git a/docs/content/troubleshooting/missing-payment-providers.md b/docs/content/troubleshooting/missing-payment-providers.md index bf1e33764f..55487b9e01 100644 --- a/docs/content/troubleshooting/missing-payment-providers.md +++ b/docs/content/troubleshooting/missing-payment-providers.md @@ -1,11 +1,12 @@ -# Payment Processor (Stripe) not showing in checkout +--- +title: 'Payment Processor not showing in checkout' +--- You add payment processors to your Medusa instance by adding them as plugins in `medusa-config.js`: ```js title=medusa-config.js const plugins = [ // ... - // You can create a Stripe account via: https://stripe.com { resolve: `medusa-payment-stripe`, options: { @@ -30,5 +31,5 @@ Then, refer to [this user guide](../user-guide/regions/providers.mdx) to learn h ## See Also -- [Install Stripe](../plugins/payment/stripe.md) +- [Install Stripe](../plugins/payment/stripe.mdx) - [Payment Architecture Overview](../modules/carts-and-checkout/payment.md) diff --git a/docs/content/troubleshooting/redis-events.md b/docs/content/troubleshooting/redis-events.md index 9dfca49ff1..191efee427 100644 --- a/docs/content/troubleshooting/redis-events.md +++ b/docs/content/troubleshooting/redis-events.md @@ -1,4 +1,6 @@ -# Redis not emitting events +--- +title: 'Redis not emitting events' +--- :::note diff --git a/docs/content/troubleshooting/s3-acl-error.md b/docs/content/troubleshooting/s3-acl-error.md index 061195ef26..48343ec4cb 100644 --- a/docs/content/troubleshooting/s3-acl-error.md +++ b/docs/content/troubleshooting/s3-acl-error.md @@ -1,6 +1,8 @@ -# S3 Plugin ACL Error +--- +title: 'S3 Plugin ACL Error' +--- -If you're using the [S3 Plugin](../plugins/file-service/s3.md) and, when you upload an image, you receive the following error on your Medusa backend: +If you're using the [S3 Plugin](../plugins/file-service/s3.mdx) and, when you upload an image, you receive the following error on your Medusa backend: ```bash noReport AccessControlListNotSupported: The bucket does not allow ACLs diff --git a/docs/content/troubleshooting/signing-in-to-admin.md b/docs/content/troubleshooting/signing-in-to-admin.md index 50f2c2b478..ec4dc526a8 100644 --- a/docs/content/troubleshooting/signing-in-to-admin.md +++ b/docs/content/troubleshooting/signing-in-to-admin.md @@ -1,4 +1,6 @@ -# Signing in to Medusa Admin +--- +title: 'Signing in to Medusa Admin' +--- If you've created a new Medusa backend and used the `seed` command, the default credentials are: @@ -17,4 +19,4 @@ npx @medusajs/medusa-cli user -e some@email.com -p somepassword ## See Also -- [Medusa CLI tool reference](../cli/reference.md) +- [Medusa CLI tool reference](../cli/reference.mdx) diff --git a/docs/content/upgrade-guides/admin/1-0-0.md b/docs/content/upgrade-guides/admin/1-0-0.md index 6f4eaedcb4..06d3070ee4 100644 --- a/docs/content/upgrade-guides/admin/1-0-0.md +++ b/docs/content/upgrade-guides/admin/1-0-0.md @@ -39,7 +39,7 @@ The move to an NPM package has implications for the workflow to deploy the Admin To host the Admin directly from your Medusa server, you can follow the [Admin Quickstart Guide](../../admin/quickstart.mdx). -You can learn how to deploy the Admin to a host through the [Vercel Deployment Guide](../../deployments/admin/deploying-on-vercel.md). The process is similar for other Git based hosting platforms. +You can learn how to deploy the Admin to a host through the [Vercel Deployment Guide](../../deployments/admin/deploying-on-vercel.mdx). The process is similar for other Git based hosting platforms. ### Preserving Customizations in the Admin diff --git a/docs/styles/docs/Acronyms.yml b/docs/styles/docs/Acronyms.yml index 269403ad46..4873e8fa0c 100644 --- a/docs/styles/docs/Acronyms.yml +++ b/docs/styles/docs/Acronyms.yml @@ -1,7 +1,7 @@ extends: conditional message: "'%s' has no definition." link: https://medusajs.notion.site/Style-Guide-Docs-fad86dd1c5f84b48b145e959f36628e0#4a59adcd20a949008302f27502921933 -level: error +level: warning ignorecase: false scope: paragraph # Ensures that the existence of 'first' implies the existence of 'second'. @@ -73,4 +73,8 @@ exceptions: - UPS - RMA - JSONB - - USD \ No newline at end of file + - USD + - SASL + - SCRAM + - FIRST + - CORS \ No newline at end of file diff --git a/www/docs/src/components/Troubleshooting/index.tsx b/www/docs/src/components/Troubleshooting/index.tsx new file mode 100644 index 0000000000..e314434535 --- /dev/null +++ b/www/docs/src/components/Troubleshooting/index.tsx @@ -0,0 +1,25 @@ +import React from "react" +import Details from "@theme/Details" + +type TroubleshootingSection = { + title: string + content: React.ReactNode +} + +type TroubleshootingProps = { + sections: TroubleshootingSection[] +} & React.AllHTMLAttributes + +const Troubleshooting: React.FC = ({ sections }) => { + return ( + <> + {sections.map(({ title, content }, index) => ( +
+ {content} +
+ ))} + + ) +} + +export default Troubleshooting