asyavee/medusa-store
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

docs: added troubleshooting component (#4255)

Browse Source
This commit is contained in:
Shahed Nasser
2023-06-06 15:18:23 +03:00
committed by GitHub
parent 926e284bac
commit b1c63c5476
64 changed files with 607 additions and 257 deletions
Download Patch File Download Diff File Expand all files Collapse all files

15
docs/content/admin/quickstart.mdx
View File

@@ -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
<Troubleshooting
sections={[
{
title: 'Signing into Admin',
content: <AdminLoginSection />
},
]}
/>

10
docs/content/cli/reference.md → docs/content/cli/reference.mdx
View File

@@ -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
<TroubleshootingSection />
---
## Common Options
The following options can be used with all available commands.

28
docs/content/create-medusa-app.mdx
View File

@@ -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.
<Troubleshooting
sections={[
{
title: "TypeError: cmd is not a function",
content: <TypeErrorSection />
},
{
title: "Error: connect ECONNREFUSED ::1:5432",
content: <ConnectionErrorSection />
},
{
title: 'AwilixResolutionError: Could Not Resolve X',
content: <FreshInstallationSection />
},
{
title: "Other Errors",
content: <OtherErrorsSection />
},
]}
/>
---

40
docs/content/deployments/admin/deploying-on-vercel.md → docs/content/deployments/admin/deploying-on-vercel.mdx
View File

@@ -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 <GITHUB_URL>
```
Where `<GITHUB_URL>` is the URL you just copied.
Where `<GITHUB_URL>` 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=<YOUR_BACKEND_URL>
```
Where `<YOUR_BACKEND_URL>` is the URL of your deployed Medusa backend.
Where `<YOUR_BACKEND_URL>` 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=<ADMIN_URL>
```
Where `<ADMIN_URL>` is the URL of your admin dashboard that you just deployed.
Where `<ADMIN_URL>` 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
<Troubleshooting
sections={[
{
title: 'CORS Error',
content: <CorsErrorSection />
},
]}
/>

2
docs/content/deployments/server/deploying-on-qovery.md
View File

@@ -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

2
docs/content/deployments/server/deploying-on-railway.md
View File

@@ -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).
---

30
docs/content/deployments/storefront/deploying-next-on-vercel.md → docs/content/deployments/storefront/deploying-next-on-vercel.mdx
View File

@@ -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 <GITHUB_URL>
```
Where `<GITHUB_URL>` is the URL you just copied.
Where `<GITHUB_URL>` 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=<STOREFRONT_URL>
```
Where `<STOREFRONT_URL>` is the URL of your Next.js storefront that you just deployed.
Where `<STOREFRONT_URL>` 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
<Troubleshooting
sections={[
{
title: 'CORS Error',
content: <CorsErrorSection />
},
]}
/>

45
docs/content/development/backend/install.mdx
View File

@@ -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
```
<Feedback
event="survey_server_quickstart"
question="Did you set up the backend successfully?"
@@ -75,7 +85,30 @@ Make sure your PostgreSQL server is running before you run the Medusa backend.
negativeQuestion="Please describe the issue you faced."
/>
### Seed Data
---
## Troubleshooting Installation
<Troubleshooting
sections={[
{
title: 'Error: SASL: SCRAM-SERVER-FIRST-MESSAGE: Client password must be a string',
content: <SaslSection />
},
{
title: 'Error: connect ECONNREFUSED ::1:5432',
content: <ConnectionErrorSection />
},
{
title: 'AwilixResolutionError: Could Not Resolve X',
content: <FreshInstallationSection />
},
]}
/>
---
## 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.

7
docs/content/development/backend/prepare-environment.mdx
View File

@@ -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).
:::
<MedusaCliTroubleshootingSection />
### PostgreSQL

25
docs/content/development/endpoints/add-middleware.md → docs/content/development/endpoints/add-middleware.mdx
View File

@@ -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
<Troubleshooting
sections={[
{
title: 'AwilixResolutionError: Could Not Resolve X',
content: <ServiceLifetimeSection />
},
{
title: 'AwilixResolutionError: Could Not Resolve X (Custom Registration)',
content: <CustomRegistrationSection />
}
]}
/>
---
## See Also
- [Store API reference](/api/store)

2
docs/content/development/endpoints/create.md
View File

@@ -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:

25
docs/content/development/endpoints/example-logged-in-user.md → docs/content/development/endpoints/example-logged-in-user.mdx
View File

@@ -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
<Troubleshooting
sections={[
{
title: 'AwilixResolutionError: Could Not Resolve X',
content: <ServiceLifetimeSection />
},
{
title: 'AwilixResolutionError: Could Not Resolve X (Custom Registration)',
content: <CustomRegistrationSection />
}
]}
/>

2
docs/content/development/entities/migrations/overview.mdx
View File

@@ -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)
---

2
docs/content/development/feature-flags/toggle.md
View File

@@ -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).
You can follow [this documentation to learn how to revert the last migration you ran](../../cli/reference.mdx#migrations).

2
docs/content/development/file-service/overview.mdx
View File

@@ -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.

4
docs/content/development/fundamentals/dependency-injection.md
View File

@@ -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)

2
docs/content/development/notification/create-notification-provider.md
View File

@@ -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).
:::

2
docs/content/development/notification/overview.mdx
View File

@@ -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.

2
docs/content/development/plugins/create.md
View File

@@ -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)

2
docs/content/development/search/overview.mdx
View File

@@ -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).

16
docs/content/development/services/create-service.md → docs/content/development/services/create-service.mdx
View File

@@ -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
<Troubleshooting
sections={[
{
title: 'AwilixResolutionError: Could Not Resolve X',
content: <ServiceLifetimeSection />
}
]}
/>
---
## See Also
- [Create a Plugin](../plugins/create.md)

18
docs/content/development/services/extend-service.md → docs/content/development/services/extend-service.mdx
View File

@@ -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
<Troubleshooting
sections={[
{
title: 'AwilixResolutionError: Could Not Resolve X (Service Lifetime)',
content: <ServiceLifetimeSection />
}
]}
/>

4
docs/content/modules/carts-and-checkout/backend/add-fulfillment-provider.md
View File

@@ -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).
:::

4
docs/content/modules/carts-and-checkout/backend/add-payment-provider.md
View File

@@ -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).
:::

2
docs/content/modules/carts-and-checkout/payment.md
View File

@@ -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.

4
docs/content/modules/carts-and-checkout/shipping.md
View File

@@ -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.

4
docs/content/modules/taxes/storefront/manual-calculation.md
View File

@@ -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.
:::

4
docs/content/plugins/analytics/segment.md
View File

@@ -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)

2
docs/content/plugins/cms/contentful/index.md
View File

@@ -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).
---

2
docs/content/plugins/cms/strapi.md
View File

@@ -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

28
docs/content/plugins/file-service/s3.md → docs/content/plugins/file-service/s3.mdx
View File

@@ -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 `<BUCKET_NAME>` is the name of the S3 bucket you’re using.
---
## Troubleshooting
<Troubleshooting
sections={[
{
title: 'Error: AccessControlListNotSupported: The bucket does not allow ACLs',
content: <AclErrorSection />
}
]}
/>
---
## 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.

2
docs/content/plugins/notifications/mailchimp.md
View File

@@ -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).
:::

2
docs/content/plugins/notifications/twilio-sms.md
View File

@@ -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.

20
docs/content/plugins/payment/stripe.md → docs/content/plugins/payment/stripe.mdx
View File

@@ -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
<Troubleshooting
sections={[
{
title: 'Stripe not showing in checkout',
content: <MissingPaymentProvider />
}
]}
/>
---
## See Also
- Check out [more plugins](../overview.mdx) you can add to your store.

24
docs/content/starters/nextjs-medusa-starter.mdx
View File

@@ -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
:::
<Troubleshooting
sections={[
{
title: 'CORS Error',
content: <CorsErrorSection />
},
{
title: 'Resolve "Cannot find module X" Errors',
content: <ModuleXErrorSection />
},
]}
/>
---
@@ -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)

78
docs/content/troubleshooting/awilix-resolution-error.md
View File

@@ -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:
<!-- eslint-disable prefer-rest-params -->
```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
```

25
docs/content/troubleshooting/awilix-resolution-error.mdx Normal file
View File

@@ -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
<ServiceLifetimeSection />
---
## Option 2: Using Try-Catch Block with Custom Registration
<CustomRegistrationSection />
---
## Option 3: Error on A Fresh Installation
<FreshInstallationSection />

27
docs/content/troubleshooting/awilix-resolution-error/_custom-registration.md Normal file
View File

@@ -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:
<!-- eslint-disable prefer-rest-params -->
```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).

5
docs/content/troubleshooting/awilix-resolution-error/_fresh-installation.md Normal file
View File

@@ -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
```

34
docs/content/troubleshooting/awilix-resolution-error/_service-lifetime.md Normal file
View File

@@ -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).

50
docs/content/troubleshooting/cli-installation-errors.mdx
View File

@@ -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).
<PermissionErrorsSection />
---
@@ -19,13 +20,7 @@ You can check out more information in [NPM’s documentation](https://docs.npmjs
<!-- vale on -->
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.
<PowershellErrorSection />
---
@@ -35,31 +30,4 @@ Try closing your Powershell window and opening a new one.
<!-- vale on -->
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:
<Tabs groupId="operating-systems" isCodeTabs={true}>
<TabItem value="unix" label="MacOS / Linux" default>
```bash
export PATH="$(yarn global bin):$PATH"
```
</TabItem>
<TabItem value="windows" label="Windows">
```bash
# MAKE SURE TO INCLUDE %path%
setx path "%path%;c:\users\YOURUSERNAME\appdata\local\yarn\bin"
# YOURUSERNAME is your account username
```
</TabItem>
</Tabs>
You can learn more in [Yarn’s documentation](https://classic.yarnpkg.com/en/docs/cli/global#adding-the-install-location-to-your-path).
<YarnError />

3
docs/content/troubleshooting/cli-installation-errors/_permission-errors.md Normal file
View File

@@ -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).

7
docs/content/troubleshooting/cli-installation-errors/_powershell-error.md Normal file
View File

@@ -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.

21
docs/content/troubleshooting/cli-installation-errors/_reusable-section.mdx Normal file
View File

@@ -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'
<Troubleshooting
sections={[
{
title: "NPM Error: EACCES Permissions Errors",
content: <PermissionErrorsSection />
},
{
title: "Powershell Error: command not found: medusa",
content: <PowershellErrorSection />
},
{
title: "Yarn Error: command not found: medusa",
content: <YarnErrorSection />
}
]}
/>

31
docs/content/troubleshooting/cli-installation-errors/_yarn-error.mdx Normal file
View File

@@ -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:
<Tabs groupId="operating-systems" isCodeTabs={true}>
<TabItem value="unix" label="MacOS / Linux" default>
```bash
export PATH="$(yarn global bin):$PATH"
```
</TabItem>
<TabItem value="windows" label="Windows">
```bash
# MAKE SURE TO INCLUDE %path%
setx path "%path%;c:\users\YOURUSERNAME\appdata\local\yarn\bin"
# YOURUSERNAME is your account username
```
</TabItem>
</Tabs>
You can learn more in [Yarn’s documentation](https://classic.yarnpkg.com/en/docs/cli/global#adding-the-install-location-to-your-path).

30
docs/content/troubleshooting/common-installation-errors.mdx
View File

@@ -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:
<Tabs groupId="operating-systems" isCodeTabs={true}>
<TabItem value="unix" label="MacOS / Linux" default>
```bash
rm -rf node_modules
yarn install
```
</TabItem>
<TabItem value="windows" label="Windows">
```bash
rd /s /q node_modules
yarn install
```
</TabItem>
</Tabs>
<ModuleXErrorSection />

25
docs/content/troubleshooting/common-installation-errors/_module-x-error.mdx Normal file
View File

@@ -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:
<Tabs groupId="operating-systems" isCodeTabs={true}>
<TabItem value="unix" label="MacOS / Linux" default>
```bash
rm -rf node_modules
yarn install
```
</TabItem>
<TabItem value="windows" label="Windows">
```bash
rd /s /q node_modules
yarn install
```
</TabItem>
</Tabs>

6
docs/content/troubleshooting/cors-issues.md
View File

@@ -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:

16
docs/content/troubleshooting/create-medusa-app-errors.md
View File

@@ -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.

16
docs/content/troubleshooting/create-medusa-app-errors.mdx Normal file
View File

@@ -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
<TypeError />
---
## Other Errors
<OtherErrors />

1
docs/content/troubleshooting/create-medusa-app-errors/_other-errors.md Normal file
View File

@@ -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.

8
docs/content/troubleshooting/create-medusa-app-errors/_typeerror.md Normal file
View File

@@ -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
```

16
docs/content/troubleshooting/database-error.mdx Normal file
View File

@@ -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
<SaslSection />
---
## Error: connect ECONNREFUSED ::1:5432
<ConnectionErrorSection />

10
docs/content/troubleshooting/database-errors/_connection-error.md Normal file
View File

@@ -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.

4
docs/content/troubleshooting/database-error.md → docs/content/troubleshooting/database-errors/_sasl.md
View File

@@ -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

4
docs/content/troubleshooting/documentation-error.md
View File

@@ -1,4 +1,6 @@
# Troubleshooting Documentation Errors
---
title: 'Troubleshooting Documentation Errors'
---
## React Hook Errors

4
docs/content/troubleshooting/errors-after-update.md
View File

@@ -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.

7
docs/content/troubleshooting/missing-payment-providers.md
View File

@@ -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)

4
docs/content/troubleshooting/redis-events.md
View File

@@ -1,4 +1,6 @@
# Redis not emitting events
---
title: 'Redis not emitting events'
---
:::note

6
docs/content/troubleshooting/s3-acl-error.md
View File

@@ -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

6
docs/content/troubleshooting/signing-in-to-admin.md
View File

@@ -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)

2
docs/content/upgrade-guides/admin/1-0-0.md
View File

@@ -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

8
docs/styles/docs/Acronyms.yml
View File

@@ -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
- USD
- SASL
- SCRAM
- FIRST
- CORS