From b0ebfd6bcf9083f988dce55cb11b21fd71537c6a Mon Sep 17 00:00:00 2001 From: Shahed Nasser Date: Mon, 26 Dec 2022 15:52:08 +0200 Subject: [PATCH] docs: added dividers + see also section (#2899) --- docs/content/add-plugins/algolia.md | 24 +++++++- .../contentful/customize-contentful.md | 14 ++++- docs/content/add-plugins/contentful/index.md | 23 +++++++- docs/content/add-plugins/klarna.md | 10 +++- docs/content/add-plugins/mailchimp.md | 18 +++++- docs/content/add-plugins/meilisearch.md | 16 ++++- docs/content/add-plugins/minio.md | 16 ++++- docs/content/add-plugins/paypal.md | 14 ++++- docs/content/add-plugins/s3.md | 20 ++++++- docs/content/add-plugins/segment.md | 21 +++++-- docs/content/add-plugins/sendgrid.mdx | 18 +++++- docs/content/add-plugins/slack.md | 14 ++++- docs/content/add-plugins/spaces.md | 20 ++++++- docs/content/add-plugins/strapi.md | 22 ++++++- docs/content/add-plugins/stripe.md | 14 ++++- docs/content/add-plugins/twilio-sms.md | 14 ++++- docs/content/admin/development.md | 6 +- docs/content/admin/quickstart.mdx | 20 ++++++- docs/content/advanced/admin/import-prices.mdx | 18 +++++- .../advanced/admin/import-products.mdx | 18 +++++- .../advanced/admin/manage-discounts.mdx | 18 +++++- .../content/advanced/admin/manage-regions.mdx | 6 +- docs/content/advanced/admin/order-edit.mdx | 8 ++- .../advanced/admin/use-customergroups-api.mdx | 6 +- .../advanced/backend/batch-jobs/create.md | 22 ++++++- .../backend/batch-jobs/customize-import.md | 12 +++- .../advanced/backend/batch-jobs/index.md | 8 ++- .../advanced/backend/customer-groups/index.md | 8 +-- .../backend/dependency-container/index.md | 16 +++-- .../advanced/backend/discounts/index.md | 6 +- .../content/advanced/backend/endpoints/add.md | 21 ++++++- .../advanced/backend/entities/index.md | 12 ++-- .../advanced/backend/entities/overview.md | 10 +++- .../advanced/backend/feature-flags/toggle.md | 14 ++++- .../advanced/backend/migrations/index.md | 10 +++- .../advanced/backend/migrations/overview.md | 10 +++- .../how-to-create-notification-provider.md | 21 +++++-- .../advanced/backend/notification/overview.md | 21 +++++-- .../payment/how-to-create-payment-provider.md | 12 +++- .../advanced/backend/payment/overview.md | 16 ++++- .../advanced/backend/plugins/create.md | 28 +++++++-- .../advanced/backend/plugins/overview.md | 10 +++- .../advanced/backend/price-lists/index.md | 6 +- .../advanced/backend/price-lists/use-api.mdx | 6 +- .../backend/price-selection-strategy/index.md | 6 +- .../price-selection-strategy/override.md | 4 +- .../advanced/backend/regions/overview.md | 6 +- .../advanced/backend/sales-channels/index.md | 6 +- .../backend/sales-channels/manage-admin.mdx | 4 +- .../advanced/backend/scheduled-jobs/create.md | 14 ++++- .../backend/services/create-service.md | 12 +++- .../advanced/backend/services/overview.md | 8 ++- .../shipping/add-fulfillment-provider.md | 9 ++- .../advanced/backend/shipping/overview.md | 18 +++++- .../backend/subscribers/create-subscriber.md | 12 +++- .../backend/subscribers/events-list.md | 58 ++++++++++++++++++- .../advanced/backend/subscribers/overview.md | 10 +++- .../backend/taxes/inclusive-pricing.md | 14 ++++- .../backend/taxes/manual-calculation.md | 10 +++- .../advanced/backend/upgrade-guides/1-3-0.md | 6 ++ .../advanced/backend/upgrade-guides/1-3-6.md | 2 + .../advanced/backend/upgrade-guides/1-3-8.md | 2 + .../advanced/backend/upgrade-guides/1-6-1.md | 2 + .../advanced/backend/upgrade-guides/1-7-0.md | 2 + .../advanced/backend/upgrade-guides/1-7-1.md | 2 + .../upgrade-guides/admin/admin-vite.md | 6 ++ .../ecommerce/handle-order-claim-event.md | 12 +++- .../storefront/handle-order-edits.mdx | 20 ++++++- .../how-to-implement-checkout-flow.mdx | 17 +++++- .../storefront/implement-claim-order.mdx | 10 +++- .../storefront/use-discounts-in-checkout.mdx | 18 ++++-- .../advanced/storefront/use-regions.mdx | 6 +- .../storefront/use-sales-channels.mdx | 14 ++++- docs/content/cli/reference.md | 14 ++++- docs/content/contribution-guidelines.md | 24 ++++++++ .../deployments/admin/deploying-on-netlify.md | 15 +++-- .../server/deploying-on-digital-ocean.md | 22 ++++++- .../server/deploying-on-heroku.mdx | 14 ++++- .../deployments/server/deploying-on-qovery.md | 18 +++++- .../server/deploying-on-railway.md | 22 ++++++- .../storefront/deploying-gatsby-on-netlify.md | 16 ++++- docs/content/guides/carts-in-medusa.mdx | 22 ++++++- docs/content/js-client/overview.md | 8 +++ docs/content/nav.yml | 41 ------------- .../content/quickstart/quick-start-docker.mdx | 10 +++- docs/content/quickstart/quick-start.mdx | 8 ++- .../starters/gatsby-medusa-starter.mdx | 18 ++++-- .../starters/nextjs-medusa-starter.mdx | 17 +++++- .../cli-installation-errors.mdx | 2 + docs/content/troubleshooting/cors-issues.md | 6 +- .../troubleshooting/documentation-error.md | 2 + .../missing-payment-providers.md | 8 ++- docs/content/troubleshooting/redis-events.md | 8 ++- .../troubleshooting/signing-in-to-admin.md | 6 +- .../transaction-error-in-checkout.md | 10 ++-- .../0-set-up-your-development-environment.mdx | 12 ++-- docs/content/usage.md | 6 ++ docs/content/usage/configurations.md | 26 +++++++-- docs/content/usage/create-medusa-app.mdx | 12 +++- docs/content/usage/local-development.md | 14 ++++- 100 files changed, 1047 insertions(+), 291 deletions(-) delete mode 100644 docs/content/nav.yml diff --git a/docs/content/add-plugins/algolia.md b/docs/content/add-plugins/algolia.md index ac14dbe712..366ccc5fde 100644 --- a/docs/content/add-plugins/algolia.md +++ b/docs/content/add-plugins/algolia.md @@ -2,6 +2,8 @@ In this document, you’ll learn how to install the [Algolia plugin](https://github.com/medusajs/medusa/tree/master/packages/medusa-plugin-algolia) and use it on both your Medusa Server and your storefront. +--- + ## Overview [Algolia](https://www.algolia.com/) is a search engine service that allows developers to integrate advanced search functionalities into their websites including typo tolerance, recommended results, and quick responses. @@ -10,6 +12,8 @@ Algolia can be used for a wide range of use cases, including ecommerce websites. Through Medusa's flexible plugin system, it is possible to add a search engine to your Medusa server and storefront using Algolia with just a few steps. +--- + ## Prerequisites ### Medusa Components @@ -28,6 +32,8 @@ If you don’t install and configure Redis on your Medusa server, the Algolia in You need to [create an Algolia account](https://www.algolia.com/users/sign_up) before you follow this documentation. Algolia offers a free plan to get started quickly. +--- + ## Create an Algolia App The first step is to create an Algolia app for your Medusa server. To create one, open the [Applications page](https://www.algolia.com/account/applications) or, on your dashboard, go to Settings then choose Applications. @@ -50,6 +56,8 @@ In the last step, you’ll see a summary of your order. If all looks good, check ![Summary of your application's order with the terms and agreement checkboxes checked](https://res.cloudinary.com/dza7lstvk/image/upload/v1668000019/Medusa%20Docs/Algolia/PTI2Swq_a1qbi5.png) +--- + ## Retrieve API Keys To retrieve the API keys that you’ll use in the next sections, go to Settings, then choose API Keys in the Team and Access section. @@ -66,6 +74,8 @@ If you have more than one application in your Algolia account, make sure you’r ![Application ID, Search-Only API Key, and Admin API Key can be found in the API Keys page](https://res.cloudinary.com/dza7lstvk/image/upload/v1668000037/Medusa%20Docs/Algolia/i50Irki_jmtyk6.png) +--- + ## Install the Algolia Plugin In the directory of your Medusa server, run the following command to install the Algolia plugin: @@ -118,6 +128,8 @@ const plugins = [ The `searchableAttributes` are the attributes in a product that are searchable, and `attributesToRetrieve` are the attributes to retrieve for each product result. You’re free to make changes to these attributes as you see fit, but these are the recommended attributes. +--- + ## Test the Algolia Plugin Run your Medusa server with the following command: @@ -150,6 +162,8 @@ This feature is only available if you have Redis installed and configured with y ::: +--- + ## Add Search to your Storefront In this section, you’ll learn how to add the UI on your storefront to allow searching with Algolia. This section has instructions for Medusa’s [Next.js](../starters/nextjs-medusa-starter.mdx) storefront as well as React-based frameworks such as the [Gatsby](../starters/gatsby-medusa-starter.mdx) storefront. @@ -213,6 +227,8 @@ To make sure the Next.js storefront properly displays the products in the search ![Search pop up in the Next.js storefront](https://res.cloudinary.com/dza7lstvk/image/upload/v1668000082/Medusa%20Docs/Algolia/1f9qqK6_c0z8zi.png) +--- + ## Add to Gatsby and React-Based Storefronts This section covers adding the search UI to React-based storefronts. It uses the Gatsby storefront as an example, but you can use the same steps on any React-based framework. @@ -327,7 +343,9 @@ If you run your Gatsby storefront while the Medusa server is running, you should ![Search bar in the Gatsby storefront](https://res.cloudinary.com/dza7lstvk/image/upload/v1668000097/Medusa%20Docs/Algolia/INtlcIo_jlh16x.png) -## What’s Next +--- -- Learn how to [deploy your Medusa server](../deployments/server/index.mdx). -- Learn how to [deploy your Gatsby storefront](../deployments/storefront/deploying-gatsby-on-netlify.md). +## See Also + +- [Deploy your Medusa server](../deployments/server/index.mdx) +- [Deploy your Gatsby storefront](../deployments/storefront/deploying-gatsby-on-netlify.md) diff --git a/docs/content/add-plugins/contentful/customize-contentful.md b/docs/content/add-plugins/contentful/customize-contentful.md index 75989cb0de..e54222ee89 100644 --- a/docs/content/add-plugins/contentful/customize-contentful.md +++ b/docs/content/add-plugins/contentful/customize-contentful.md @@ -12,10 +12,14 @@ On your storefront, you can add any necessary components that can render the Con As an example to explain this process, in this documentation, you’ll create a migration that creates a Rich Text content model in Contentful and edits the Page and Product content models to allow using Rich Text content as a tile in pages and products. Then, you’ll modify the Gatsby storefront to render the Rich Text content model. +--- + ## Prerequisites It’s assumed you already have set up a Medusa server integrated with Contentful and have a Gatsby storefront integrated with Contentful. If not, [please follow this documentation first](index.md). +--- + ## Create a Contentful Migration The Contentful migrations are located in the `contentful-migrations` directory in the Medusa Contentful server starter. So, if you want to create your own Contentful migrations, you can create them under that directory. @@ -144,6 +148,8 @@ Similarly, you can add Rich Text content to any product page. ![A rich text content is added to a product](https://res.cloudinary.com/dza7lstvk/image/upload/v1668001305/Medusa%20Docs/Contentful/wgI8mEB_wbukpd.png) +--- + ## Render New Content Models in the Storefront After creating a new content model in your Contentful Space, you must add the necessary component to render it in your Gatsby storefront. @@ -308,7 +314,9 @@ Restart the Gatsby storefront then open a product that you added Rich Text conte ![Rich Text content you added to the product should be visible at the end of the page](https://res.cloudinary.com/dza7lstvk/image/upload/v1668001342/Medusa%20Docs/Contentful/LGiVMxx_rqsr2l.png) -## What’s Next +--- -- Learn how to deploy your Medusa server to [Heroku](../../deployments/server/deploying-on-heroku.mdx), [Qovery](../../deployments/server/deploying-on-qovery.md), or [DigitalOcean](../../deployments/server/deploying-on-digital-ocean.md). -- Learn [how to deploy your Gatsby storefront to Netlify](../../deployments/storefront/deploying-gatsby-on-netlify.md). +## See Also + +- Deploy your Medusa server to [Heroku](../../deployments/server/deploying-on-heroku.mdx), [Qovery](../../deployments/server/deploying-on-qovery.md), or [DigitalOcean](../../deployments/server/deploying-on-digital-ocean.md). +- [How to deploy your Gatsby storefront to Netlify](../../deployments/storefront/deploying-gatsby-on-netlify.md). diff --git a/docs/content/add-plugins/contentful/index.md b/docs/content/add-plugins/contentful/index.md index df584e59a6..6fdd84029a 100644 --- a/docs/content/add-plugins/contentful/index.md +++ b/docs/content/add-plugins/contentful/index.md @@ -8,6 +8,8 @@ In this document, you’ll learn how to integrate a Medusa server with Contentfu By integrating Contentful to Medusa, you can benefit from powerful features in your ecommerce store including detailed product CMS details, easy-to-use interface to use for static content and pages, localization, and much more. +--- + ## Prerequisites ### Needed Accounts @@ -22,6 +24,8 @@ By integrating Contentful to Medusa, you can benefit from powerful features in y - 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). +--- + ## Install Medusa Server Using Contentful Starter Instead of using the default Medusa Server starter, you must use the [Contentful starter](https://github.com/medusajs/medusa-starter-contentful) to install a server that is ready to be used with Contentful. This server contains all the necessary files to make the integration work. @@ -181,10 +185,14 @@ If you seeded the database with demo data, you should see that events related to The Contentful integration ensures a two-way sync between the Medusa server and Contentful. So, when new products are added to Medusa, these products will be added to your Contentful Space as well. +--- + ## (Optional) Add Products with the Medusa Admin Using the Medusa admin, you can add products to your Medusa server. This will trigger product events that subsequently add these products to Contentful. +--- + ## Manage Contentful Data ### Publish Products @@ -217,6 +225,8 @@ Once you’re done adding products, click on Publish changes in the right sideba ![Click on the publish changes button on the right](https://res.cloudinary.com/dza7lstvk/image/upload/v1668001508/Medusa%20Docs/Contentful/URNpkXq_cb5ppp.png) +--- + ## Setup Gatsby Storefront In this section, you’ll set up the Gatsby storefront of your Medusa server. @@ -264,6 +274,8 @@ This starts the storefront at `localhost:8000`. Open it in your browser and you ![The storefront with the featured products section](https://res.cloudinary.com/dza7lstvk/image/upload/v1668001537/Medusa%20Docs/Contentful/f6xwYbS_w1v993.png) +--- + ## Make Changes to Content You can update the CMS content of your storefront in your Contentful Space. This includes the CMS pages or product details. @@ -274,8 +286,13 @@ If you make changes to the data while your Gatsby storefront is running, the cha ::: +--- + ## What’s Next -- Learn [how to customize your Contentful server and storefront](./customize-contentful.md). -- Learn how to deploy your Medusa server to [Heroku](../../deployments/server/deploying-on-heroku.mdx), [Qovery](../../deployments/server/deploying-on-qovery.md), or [DigitalOcean](../../deployments/server/deploying-on-digital-ocean.md). -- Learn [how to deploy your Gatsby storefront to Netlify](../../deployments/storefront/deploying-gatsby-on-netlify.md). +Learn [How to customize your Contentful server and storefront](./customize-contentful.md). + +## See Also + +- How to deploy your Medusa server to [Heroku](../../deployments/server/deploying-on-heroku.mdx), [Qovery](../../deployments/server/deploying-on-qovery.md), or [DigitalOcean](../../deployments/server/deploying-on-digital-ocean.md). +- [How to deploy your Gatsby storefront to Netlify](../../deployments/storefront/deploying-gatsby-on-netlify.md). diff --git a/docs/content/add-plugins/klarna.md b/docs/content/add-plugins/klarna.md index 60ab91e992..7afe2b3a9b 100644 --- a/docs/content/add-plugins/klarna.md +++ b/docs/content/add-plugins/klarna.md @@ -8,6 +8,8 @@ In this document, you’ll learn how to integrate Klarna as a payment provider i You can integrate Klarna into Medusa using the [official plugin](https://github.com/medusajs/medusa/tree/master/packages/medusa-payment-klarna). +--- + ## Prerequisites ### Medusa Components @@ -20,6 +22,8 @@ In addition, you’ll need to use the [Medusa Admin](../admin/quickstart.mdx) to - A [Klarna business account](https://portal.klarna.com/) +--- + ## Install Plugin On your Medusa server, run the following command to install the plugin: @@ -69,12 +73,16 @@ const plugins = [ ]; ``` +--- + ## Enable Klarna in Regions To use Klarna in your store, you must enable it in at least one region. You can follow [this user guide to learn how to enable a payment provider in a region](../user-guide/regions/providers#manage-payment-providers). You can alternatively use the [REST APIs](/api/admin/#tag/Region/operation/PostRegionsRegionPaymentProviders). -## What’s Next +--- + +## See Also - Check out [more plugins](https://github.com/medusajs/medusa/tree/master/packages) you can add to your store. diff --git a/docs/content/add-plugins/mailchimp.md b/docs/content/add-plugins/mailchimp.md index 009b4c21ee..eed61cf6f9 100644 --- a/docs/content/add-plugins/mailchimp.md +++ b/docs/content/add-plugins/mailchimp.md @@ -14,12 +14,16 @@ This plugin is only used to allow your customers to subscribe but does not actua ::: +--- + ## Prerequisites Before going further with this guide make sure you have a Medusa server set up. You can follow the [Quickstart guide](https://docs.medusajs.com/quickstart/quick-start). You also need a Mailchimp account, so please [create one](https://mailchimp.com/signup) before you start. +--- + ## Obtain Mailchimp Keys To integrate the plugin into Medusa you need two keys: The API Key and the Newsletter list or Audience ID. The API Key acts as a credential for your account, whereas the Newsletter list ID determines which audience should the subscribed customers be added to. @@ -28,6 +32,8 @@ You can follow [this guide](https://mailchimp.com/help/about-api-keys/#Find_or_g You can follow [this guide](https://mailchimp.com/help/find-audience-id/) from Mailchimp’s documentation to obtain your Newsletter list or Audience ID. +--- + ## Install the Plugin In the directory of your Medusa server, run the following command to install the Mailchimp plugin: @@ -64,6 +70,8 @@ const plugins = [ ]; ``` +--- + ## Test it Out This plugin adds a new `POST` endpoint at `/mailchimp/subscribe`. This endpoint requires in the body of the request an `email` field. You can also optionally include a `data` object that holds any additional data you want to send to Mailchimp. You can check out [Mailchimp’s subscription documentation](https://mailchimp.com/developer/marketing/api/list-members/add-member-to-list/) for more details on the data you can send. @@ -101,6 +109,8 @@ Here’s an example of sending additional data with the subscription: All fields inside `data` will be sent to Mailchimp’s API along with the email. +--- + ## Use Mailchimp Service If you want to subscribe to users without using this endpoint or at a specific place in your code, you can use Mailchimp’s service `mailchimpService` in your endpoints, services, or subscribers. This service has a method `subscribeNewsletter` which lets you use the subscribe functionality. @@ -122,6 +132,8 @@ You can learn more about how you can use services in your endpoints, services, a ::: +--- + ## Add Subscription Form This section has a simple example of adding a subscription form in your storefront. The code is for React-based frameworks but you can use the same logic for your storefronts regardless of the framework you are using. @@ -177,7 +189,9 @@ This will result in a subscription form similar to the following: If you try entering an email and clicking Subscribe, the email will be subscribed to your Mailchimp newsletter successfully. -## What’s Next +--- + +## See Also - Check out [SendGrid plugin](../add-plugins/sendgrid.mdx) for more Email functionalities. -- [Learn more about plugins.](../advanced/backend/plugins/overview.md) +- [Plugins Overview](../advanced/backend/plugins/overview.md) diff --git a/docs/content/add-plugins/meilisearch.md b/docs/content/add-plugins/meilisearch.md index bcb7a3a67b..b1f5f6c116 100644 --- a/docs/content/add-plugins/meilisearch.md +++ b/docs/content/add-plugins/meilisearch.md @@ -10,6 +10,8 @@ MeiliSearch also provides a pleasant developer experience, as it is extremely in Through Medusa's flexible plugin system, it is possible to add a search engine to your Medusa server and storefront using MeiliSearch with just a few steps. +--- + ## Prerequisites ### Medusa Components @@ -30,6 +32,8 @@ You must install MeiliSearch to use it with Medusa. You can follow [this documen Furthermore, you should create a master key for your MeiliSearch instance. If you don’t have one created, follow [this guide](https://docs.meilisearch.com/learn/security/master_api_keys.html#protecting-a-meilisearch-instance) to create a master key. +--- + ## Install the MeiliSearch Plugin In the directory of your Medusa server, run the following command to install the MeiliSearch plugin: @@ -77,6 +81,8 @@ const plugins = [ You can change the `searchableAttributes` and `displayedAttributes` as you see fit. However, the attributes included are the recommended attributes. +--- + ## Test MeiliSearch Plugin Make sure your MeiliSearch instance is running. If you’re unsure how to run it, you can check the [installation documentation](https://docs.meilisearch.com/learn/getting_started/quick_start.html#setup-and-installation) for the command to run the MeiliSearch instance. @@ -105,6 +111,8 @@ This feature is only available if you have Redis installed and configured with y ::: +--- + ## Add Search to your Storefront In this section, you’ll learn how to add the UI on your storefront to allow searching with MeiliSearch. This section has instructions for Medusa’s [Next.js](../starters/nextjs-medusa-starter.mdx) storefront as well as React-based frameworks such as the [Gatsby storefront](../starters/gatsby-medusa-starter.mdx). @@ -286,7 +294,9 @@ If you run your Gatsby storefront while the Medusa server and the MeiliSearch in ![Search box in the header of the storefront](https://res.cloudinary.com/dza7lstvk/image/upload/v1668000317/Medusa%20Docs/MeiliSearch/ZkRgF2h_ytnpv9.png) -## What’s Next +--- -- Learn how to [deploy your Medusa server](../deployments/server/index.mdx). -- Learn how to [deploy your Gatsby storefront](./../deployments/storefront/deploying-gatsby-on-netlify.md). +## See Also + +- [Deploy your Medusa server](../deployments/server/index.mdx). +- [Deploy your Gatsby storefront](./../deployments/storefront/deploying-gatsby-on-netlify.md). diff --git a/docs/content/add-plugins/minio.md b/docs/content/add-plugins/minio.md index 5848cb71e9..7204fd86ca 100644 --- a/docs/content/add-plugins/minio.md +++ b/docs/content/add-plugins/minio.md @@ -8,10 +8,14 @@ To manage images in Medusa, you need a file service plugin responsible for hosti Medusa provides three different options to handle your file storage. This document will focus on setting up [MinIO](https://min.io) on your local machine and connecting Medusa to it. +--- + ## Prerequisites A Medusa server is required to be set up before following along with this document. You can follow the [quickstart guide](../quickstart/quick-start.mdx) to get started in minutes. +--- + ## Set up MinIO You can follow [MinIO’s guide to install it](https://docs.min.io/minio/baremetal/quickstart/quickstart.html) on your machine based on your operating system. @@ -76,6 +80,8 @@ You will not be able to access the Secret Key after closing the pop-up. So, make ::: +--- + ## Plugin Installation In the directory of your Medusa server, run the following command to install the MinIO plugin: @@ -115,12 +121,16 @@ If you have multiple storage plugins configured, the last plugin declared in the ::: +--- + ## Test it Out Run your Medusa server alongside the [Medusa Admin](../admin/quickstart.mdx) to try out your new file service. Upon editing or creating products, you can now upload thumbnails and images, that are stored in a MinIO server. ![Image Uploaded on Admin](https://res.cloudinary.com/dza7lstvk/image/upload/v1668000429/Medusa%20Docs/MinIO/alabX2i_dzg2mh.png) +--- + ## Private Buckets ### Handle Exports @@ -181,6 +191,8 @@ Then, add two new options to the plugin’s options in `medusa-config.js`: }, ``` +--- + ## 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 MinIO domain name into the configured images domain names. This is because all URLs of product images will be from the MinIO server. @@ -207,6 +219,8 @@ module.exports = withStoreConfig({ Where `127.0.0.1` is the domain of your local MinIO server. -## What’s Next +--- + +## See Also - Check out [more plugins](https://github.com/medusajs/medusa/tree/master/packages) you can add to your store. diff --git a/docs/content/add-plugins/paypal.md b/docs/content/add-plugins/paypal.md index 31fdaffa9a..15d4164c10 100644 --- a/docs/content/add-plugins/paypal.md +++ b/docs/content/add-plugins/paypal.md @@ -10,6 +10,8 @@ As a developer, you can use PayPal’s SDKs and APIs to integrate PayPal as a pa Using the `medusa-payment-paypal` plugin, this guide shows you how to set up your Medusa server with PayPal as a payment provider. +--- + ## Prerequisites Before you proceed with this guide, make sure you create a [PayPal account](https://www.paypal.com). You also need a PayPal Developer account and retrieve the Client ID and Client Secret. You can learn more about how to do that in [PayPal’s documentation](https://developer.paypal.com/api/rest/). @@ -22,6 +24,8 @@ Additionally, you need a Medusa server installed and set up. If not, you can fol You also need [Medusa Admin](../admin/quickstart.mdx) installed to enable PayPal as a payment provider. You can alternatively use the [REST APIs](https://docs.medusajs.com/api/admin). +--- + ## Medusa Server ### Install the PayPal Plugin @@ -68,6 +72,8 @@ const plugins = [ That’s all you need to install PayPal on your Medusa server! +--- + ## Admin Setup This section will guide you through adding PayPal as a payment provider in a region using your Medusa admin dashboard. @@ -82,6 +88,8 @@ If you don’t have a Medusa admin installed, make sure to follow along with [th You can refer to [this documentation in the user guide](../user-guide/regions/providers.mdx#manage-payment-providers) to learn how to add a payment provider like PayPal to a region. +--- + ## Storefront Setup This section will take you through the steps to add PayPal as a payment method on the storefront. It includes the steps necessary when using one of Medusa’s official storefronts as well as your own custom React-based storefront. @@ -384,6 +392,8 @@ If you run the Medusa server and the storefront server, you should see the PayPa ![PayPal Button](https://res.cloudinary.com/dza7lstvk/image/upload/v1668000492/Medusa%20Docs/PayPal/PsibgPY_xtqdli.png) +--- + ## Capture Payments After the customer places an order, you can see the order on the admin panel. In the payment information under the “Payment” section, you should see a “Capture” button. @@ -394,6 +404,8 @@ Clicking this button lets you capture the payment for an order. You can also ref Refunding or Capturing payments is reflected in your PayPal dashboard as well. -## What's Next +--- + +## See Also - Check out [more plugins](https://github.com/medusajs/medusa/tree/master/packages) you can add to your store. diff --git a/docs/content/add-plugins/s3.md b/docs/content/add-plugins/s3.md index 846f3e7b94..4873adf8b1 100644 --- a/docs/content/add-plugins/s3.md +++ b/docs/content/add-plugins/s3.md @@ -8,6 +8,8 @@ To manage images in Medusa, you need a file service plugin responsible for hosti Medusa provides three different options to handle your file storage. This document focuses on using [S3](https://aws.amazon.com/s3/) to store your Medusa server’s images. +--- + ## Prerequisites ### Medusa Server @@ -18,6 +20,8 @@ A Medusa server is required to be set up before following along with this docume You need to [create an AWS account](https://console.aws.amazon.com/console/home?nc2=h_ct&src=header-signin) to follow along with this documentation. +--- + ## Create S3 Bucket On your AWS Console, search for S3 in the search box at the top. Then, choose the first result you see which should be S3 under the Services category. @@ -42,6 +46,8 @@ Then, in the “Block Public Access settings for this bucket” section, uncheck You can leave the rest of the fields in the form as is and scroll down to the end of the page. Then, click on the Create Bucket button. +--- + ## Manage Bucket Policies On the page of the bucket you just created, click on the Permissions tab. Then, scroll down until you find the Bucket policy section. Click on Edit in that section. @@ -80,6 +86,8 @@ Your user must have the `AmazonS3FullAccess` policy attached to it. You can refe You must obtain access keys for your user as you’ll use them to integrate the S3 plugin in Medusa with your bucket. To obtain the Access Key ID and the Secret Access Key, check out [this guide](https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys). +--- + ## Install the S3 Plugin In the directory of your Medusa server, run the following command to install the S3 Plugin: @@ -157,6 +165,8 @@ If you have multiple storage plugins configured, the last plugin declared in the ::: +--- + ## Test the S3 Plugin Run your Medusa server with the following command: @@ -175,6 +185,8 @@ You can also check that the image was uploaded on the S3 bucket’s page. ![Image is now available in the S3 Bucket](https://res.cloudinary.com/dza7lstvk/image/upload/v1668000630/Medusa%20Docs/S3/NJZ5bP8_ovv9rc.png) +--- + ## 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. @@ -201,8 +213,10 @@ module.exports = withStoreConfig({ Where `` is the name of the S3 bucket you’re using. -## What’s Next +--- + +## See Also - Check out [more plugins](https://github.com/medusajs/medusa/tree/master/packages) you can add to your store. -- Learn how to [deploy the Medusa server](../deployments/server/index.mdx). -- Learn about the [Next.js](../starters/nextjs-medusa-starter.mdx) and [Gatsby](../starters/gatsby-medusa-starter.mdx) storefronts. +- [Deploy the Medusa server](../deployments/server/index.mdx) +- Install the [Next.js](../starters/nextjs-medusa-starter.mdx) or [Gatsby](../starters/gatsby-medusa-starter.mdx) storefronts. diff --git a/docs/content/add-plugins/segment.md b/docs/content/add-plugins/segment.md index 63dc01dd5f..67c17453c4 100644 --- a/docs/content/add-plugins/segment.md +++ b/docs/content/add-plugins/segment.md @@ -36,6 +36,8 @@ Check out the [Event Reference](../advanced/backend/subscribers/events-list.md) ::: +--- + ## Prerequisites ### Medusa Server @@ -48,6 +50,8 @@ In addition, make sure to have Redis installed and configured with your Medusa s You need to [create a Segment account](https://app.segment.com/signup/) to follow along with the tutorial. Segment offers a free plan to get started quickly. +--- + ## Create a Segment Source On your Segment dashboard, choose Catalog from the sidebar under Connections. @@ -84,6 +88,8 @@ You can then choose from a list of destinations such as Google Universal Analyti The process of integrating each destination is different, so you must follow the steps detailed in Segment for each destination you choose. +--- + ## Install the Segment Plugin In the directory of your Medusa server, run the following command to install the Segment plugin: @@ -114,6 +120,8 @@ const plugins = [ ]; ``` +--- + ## Test the Plugin Run your server with the following command: @@ -136,6 +144,8 @@ If the data is not appearing on the destination, the issue is related to your co ::: +--- + ## Add Custom Tracking In some cases, you might want to track more events or custom events. You can do that using the `SegmentService` provided by the Segment Plugin. @@ -185,8 +195,11 @@ After adding the above subscriber, run your server again if it isn’t running a ![The customer created event is recoreded on the Segment source](https://res.cloudinary.com/dza7lstvk/image/upload/v1668000759/Medusa%20Docs/Segment/4LD41xE_qungdw.png) -## What’s Next +--- -- Learn how [services](../advanced/backend/services/create-service.md) and [subscribers](../advanced/backend/subscribers/create-subscriber.md) work. -- Check out a [full list of events](../advanced/backend/subscribers/events-list.md) in Medusa. -- Learn how to [deploy the Medusa server](../deployments/server/index.mdx). +## See Also + +- [Services Overview](../advanced/backend/services/create-service.md) +- [Subscribers Overview](../advanced/backend/subscribers/create-subscriber.md) +- [Events Reference](../advanced/backend/subscribers/events-list.md) +- [Deploy the Medusa server](../deployments/server/index.mdx) diff --git a/docs/content/add-plugins/sendgrid.mdx b/docs/content/add-plugins/sendgrid.mdx index 83ee3f4346..edb3495ba1 100644 --- a/docs/content/add-plugins/sendgrid.mdx +++ b/docs/content/add-plugins/sendgrid.mdx @@ -20,12 +20,16 @@ By integrating SendGrid with Medusa, you’ll be sending email notifications to 4. User-related events including reset passwords. 5. Restock Notifications for when product stocks are low. +--- + ## Prerequisites Before going further with this guide make sure you have a Medusa server set up. You can follow the [Quickstart guide](../quickstart/quick-start.mdx). You also must have [Redis configured on your Medusa server](/tutorial/set-up-your-development-environment#redis). Sending emails is done through Subscribers, which uses Redis as the event queue. If you don’t set up Redis, the plugin will not send emails. +--- + ## Create a SendGrid Account If you don’t have a SendGrid account, make sure to [create one](https://signup.sendgrid.com) first. You also need to set up a [single sender](https://docs.sendgrid.com/ui/sending-email/sender-verification) first in SendGrid before you can start sending emails. @@ -60,6 +64,8 @@ Medusa supports localization so you can also create multiple templates for multi ::: +--- + ## Template Reference This section covers the template types supported by the plugin and what variables you can expect in your dynamic template. You can use the variables to add details like order total or customer name. @@ -3891,6 +3897,8 @@ You don’t have to create a template for every type in the reference. You can s ``` +--- + ## Install the SendGrid Plugin In the directory of your Medusa server run the following command to install the SendGrid plugin: @@ -3941,6 +3949,8 @@ The `api_key` and `from` options are required. Then, use the key of each templat You can also optionally pass the option `localization` if you want to support different languages. `localization` accepts an object that has the country and language codes as keys. The value for each code should be an object of template keys and their IDs as values. Make sure to include the localized template IDs in `.env` as well. +--- + ## Test it Out Run your server now: @@ -3961,7 +3971,9 @@ You can also track analytics related to emails sent from the SendGrid dashboard. ![SendGrid Analytics](https://res.cloudinary.com/dza7lstvk/image/upload/v1668000788/Medusa%20Docs/SendGrid/X01LigH_mxmtbn.png) -## What’s Next +--- -- Learn more about how [Notifications work in Medusa](../advanced/backend/notification/overview.md). -- Install the [Medusa admin](https://github.com/medusajs/admin#-setting-up-admin) for functionalities like Gift Cards creation, swaps, claims, order return requests, and more. \ No newline at end of file +## See Also + +- [Notifications Overview](../advanced/backend/notification/overview.md) +- Install the [Medusa admin](../admin/quickstart.mdx) for functionalities like Gift Cards creation, swaps, claims, order return requests, and more. \ No newline at end of file diff --git a/docs/content/add-plugins/slack.md b/docs/content/add-plugins/slack.md index af352f24af..f9b25b058e 100644 --- a/docs/content/add-plugins/slack.md +++ b/docs/content/add-plugins/slack.md @@ -17,6 +17,8 @@ The plugin registers a subscriber to the `order.placed` event. When an order is Then, the order notificaiton is sent to Slack using Webhooks. So, you'll need to create a Slack App, add it into your workspace, and activate Incoming Webhooks. +--- + ## Prerequisites ### Slack Account @@ -35,6 +37,8 @@ As the Slack plugin will listen to the `order.placed` event to know when to send You can read the [Set up your development enviornment guideline](../tutorial/0-set-up-your-development-environment.mdx#redis) to learn more about how you can install and setup Redis. +--- + ## Create Slack App The first step is to create a Slack app. This app will be connected to your workspace and will have Incoming Webhooks activated to receive notifications from the Medusa server using a Webhook URL. @@ -63,6 +67,8 @@ After that, choose the channel to send the notifications to. You can also choose This will create a new Webhook with a URL which you can see in the table at the end of the Incoming Webhooks page. Copy the URL as you’ll use it in the next section. +--- + ## Install Slack Plugin The next step is to install Medusa’s [Slack plugin](https://github.com/medusajs/medusa/tree/master/packages/medusa-plugin-slack-notification) into your Medusa server. @@ -95,7 +101,9 @@ const plugins = [ That’s all you need to do to integrate Slack into Medusa! -## What's Next +--- -- Install [Medusa's Admin](https://github.com/medusajs/admin) for the full order-management experience. -- Add a Storefront to your Medusa server using [the Next.js starter](https://docs.medusajs.com/starters/nextjs-medusa-starter) or [the Gatsby starter](https://docs.medusajs.com/starters/gatsby-medusa-starter). +## See Also + +- Install [Medusa's Admin](../admin/quickstart.mdx) for the full order-management experience. +- Install the [Next.js](../starters/nextjs-medusa-starter.mdx) or [Gatsby](../starters/gatsby-medusa-starter.mdx) starter storefronts. diff --git a/docs/content/add-plugins/spaces.md b/docs/content/add-plugins/spaces.md index 4ab1a94fe1..a2f3f09aae 100644 --- a/docs/content/add-plugins/spaces.md +++ b/docs/content/add-plugins/spaces.md @@ -14,6 +14,8 @@ To manage images in Medusa, you need a file service plugin responsible for hosti Medusa provides three different options to handle your file storage. This document focuses on using [Spaces](https://www.digitalocean.com/products/spaces) to store your Medusa server’s images. +--- + ## Prerequisites ### Medusa Server @@ -24,6 +26,8 @@ A Medusa server is required to be set up before following along with this docume You need to [create a DigitalOcean account](https://cloud.digitalocean.com/registrations/new) to follow along with this documentation. A credit card is required during registration. +--- + ## Create DigitalOcean Space In your DigitalOcean account, click on the Create button at the top right, then choose Spaces from the dropdown. @@ -40,6 +44,8 @@ In the Finalize and Create section, enter a name for the field “Choose a uniqu Once you’re done, click on the Create a Space button. This creates the Space and redirects you to the Space’s page. +--- + ## Create Space Access Keys Choose API from the bottom of the sidebar. @@ -62,6 +68,8 @@ The secret access key will not be shown again after you leave the page. Make sur ::: +--- + ## Install the Spaces Plugin In the directory of your Medusa server, run the following command to install the Spaces plugin: @@ -117,6 +125,8 @@ If you have multiple storage plugins configured, the last plugin declared in the ::: +--- + ## Test the Space Plugin Run your Medusa server with the following command: @@ -135,6 +145,8 @@ You can also check that the image was uploaded on the Space’s page. ![Image can be seen on the Space's page on DigitalOcean](https://res.cloudinary.com/dza7lstvk/image/upload/v1668001050/Medusa%20Docs/Spaces/BexmRkg_gimk1d.png) +--- + ## 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 Space’s domain name into the configured images’ domain names. This is because all URLs of product images will be from the Space. @@ -161,8 +173,10 @@ module.exports = withStoreConfig({ Where `` is the domain name for your Space which can be retrieved from the Space URL. For example, `medusa-server.fra1.digitaloceanspaces.com`. -## What’s Next +--- + +## See Also - Check out [more plugins](https://github.com/medusajs/medusa/tree/master/packages) you can add to your store. -- Learn how to [deploy the Medusa server on DigitalOcean](../deployments/server/deploying-on-digital-ocean.md). -- Learn about the [Next.js](../starters/nextjs-medusa-starter.mdx) and [Gatsby](../starters/gatsby-medusa-starter.mdx) storefronts. +- [Seploy the Medusa server on DigitalOcean](../deployments/server/deploying-on-digital-ocean.md). +- Install the [Next.js](../starters/nextjs-medusa-starter.mdx) or [Gatsby](../starters/gatsby-medusa-starter.mdx) storefront. diff --git a/docs/content/add-plugins/strapi.md b/docs/content/add-plugins/strapi.md index 082f96ea9a..b926bcf2e2 100644 --- a/docs/content/add-plugins/strapi.md +++ b/docs/content/add-plugins/strapi.md @@ -14,6 +14,8 @@ This plugin is a [community plugin](https://github.com/Deathwish98/medusa-plugin By integrating Strapi to Medusa, you can benefit from powerful features in your ecommerce store including detailed product CMS details, [two-way sync](#test-two-way-sync), an easy-to-use interface to use for static content and pages, and much more. +--- + ## Prerequisites ### Medusa CLI @@ -24,6 +26,8 @@ By integrating Strapi to Medusa, you can benefit from powerful features in your Redis is required for the Strapi plugin to work as expected on your Medusa server. If you don’t have it installed, you can learn [how to install it in this documentation](../tutorial/0-set-up-your-development-environment.mdx#redis). +--- + ## Create Strapi Project The first step is to create a Strapi project using the Medusa template: @@ -52,6 +56,8 @@ Click on the Create new entry button at the top right. This opens a new form to Enter the user’s username, email, and password. Once you’re done, click on the Save button at the top right. +--- + ## Modify Permissions By default, created users have the “Authenticated” role. Before you start using the Strapi plugin on your Medusa server, you must modify this role’s permissions to allow making changes to Medusa’s models in Strapi. @@ -62,6 +68,8 @@ On your Strapi dashboard, go to Settings → Roles → Authenticated. Then, unde Once you’re done, click the Save button at the top right. +--- + ## Create Medusa Server :::note @@ -100,6 +108,8 @@ It is also recommended to use PostgreSQL for an optimal experience, however, it ::: +--- + ## Install the Strapi Plugin In the directory of your Medusa server, run the following command to install the Strapi plugin: @@ -144,6 +154,8 @@ const plugins = [ ]; ``` +--- + ## Run Medusa Server Make sure the Strapi server is still running. If not, you can run the following command to run the Strapi server in the directory of the Strapi project: @@ -160,6 +172,8 @@ npm run start Once you start your Medusa server, if you ran the `--seed` command when you created your Medusa server, you’ll see that `product.created` events have been triggered along with similar events. This will update Strapi with the products you seeded. +--- + ## Test Two-Way Sync This plugin ensures a two-way sync between the Medusa server and the Strapi server. So, if you update data on Strapi, it will be reflected on your Medusa server, and vice-versa. @@ -172,7 +186,9 @@ Try updating any products on Strapi by going to Content Manager → Products and If you try to update products on Medusa either using the [REST APIs](https://docs.medusajs.com/api/admin/#tag/Product/operation/PostProductsProduct) or using [the Medusa Admin](../user-guide/products/manage.mdx), you’ll see that the product is also updated on Strapi. -## What’s Next +--- -- Learn [how to deploy the Medusa server](../deployments/server/index.mdx). -- Learn [how to create your own plugin](../advanced/backend/plugins/create.md). +## See Also + +- [Deploy the Medusa server](../deployments/server/index.mdx) +- [Create your own plugin](../advanced/backend/plugins/create.md) diff --git a/docs/content/add-plugins/stripe.md b/docs/content/add-plugins/stripe.md index 450ddd05ba..b8b5bd0443 100644 --- a/docs/content/add-plugins/stripe.md +++ b/docs/content/add-plugins/stripe.md @@ -18,10 +18,14 @@ You can also follow this video guide to learn how the setup works: Using the `medusa-payment-stripe` plugin, this guide shows you how to set up your Medusa project with Stripe as a payment provider. +--- + ## Prerequisites Before you proceed with this guide, make sure you create a [Stripe account](https://stripe.com). You’ll later retrieve the API Keys and secrets from your account to connect Medusa to your Stripe account. +--- + ## Medusa Server This section guides you over the steps necessary to add Stripe as a payment provider to your Medusa server. @@ -95,6 +99,8 @@ After the Webhook is created, you’ll see "Signing secret" in the Webhook detai STRIPE_WEBHOOK_SECRET=whsec_... ``` +--- + ## Admin Setup This section will guide you through adding Stripe as a payment provider in a region using your Medusa admin dashboard. @@ -109,6 +115,8 @@ If you don’t have a Medusa admin installed, make sure to follow along with [th You can refer to [this documentation in the user guide](../user-guide/regions/providers.mdx#manage-payment-providers) to learn how to add a payment provider like Stripe to a region. +--- + ## Storefront Setup This guide will take you through how to set up Stripe payments in your Medusa storefront. It includes the steps necessary when using one of Medusa’s official storefronts as well as your own custom React-based storefront. @@ -346,6 +354,8 @@ If you run your server and storefront now, you’ll see the Stripe UI element an ![Stripe Form](https://res.cloudinary.com/dza7lstvk/image/upload/v1668001190/Medusa%20Docs/Stripe/NOi8THw_xv3zsx.png) +--- + ## Capture Payments After the customer places an order, you’ll be able to see the order on the admin panel. In the payment information under the “Payment” section, you should see a “Capture” button. @@ -356,6 +366,8 @@ Clicking this button allows you to capture the payment for an order. You can als Refunding or Capturing payments is reflected in your Stripe’s dashboard as well. This gives you access to all of Stripe’s analytical capabilities. -## What’s Next +--- + +## See Also - Check out [more plugins](https://github.com/medusajs/medusa/tree/master/packages) you can add to your store. diff --git a/docs/content/add-plugins/twilio-sms.md b/docs/content/add-plugins/twilio-sms.md index 0b7887979f..8af5294e23 100644 --- a/docs/content/add-plugins/twilio-sms.md +++ b/docs/content/add-plugins/twilio-sms.md @@ -14,16 +14,22 @@ This plugin only gives you access to the Twilio SMS API but does not implement s ::: +--- + ## Prerequisites Before going further with this guide make sure you have a Medusa server set up. You can follow the [Quickstart guide](../quickstart/quick-start.mdx) if you don’t. You also must have a [Twilio account created](https://www.twilio.com/sms) so if you don’t already please go ahead and create one. +--- + ## Retrieve Credentials For the [Twilio SMS plugin](https://github.com/medusajs/medusa/tree/master/packages/medusa-plugin-twilio-sms), you need three credentials from your Twilio account: Account SID, Auth Token, and a Twilio phone number to send from. You can find these three from your [Twilio Console’s homepage](https://console.twilio.com). +--- + ## Install Plugin In the directory of your Medusa server, run the following command to install [Twilio SMS plugin](https://github.com/medusajs/medusa/tree/master/packages/medusa-plugin-twilio-sms): @@ -58,6 +64,8 @@ const plugins = [ ]; ``` +--- + ## Example Usage of the Plugin This plugin adds the service `twilioSmsService` to your Medusa server. To send SMS using it, all you have to do is resolve it in your file as explained in the [Services](../advanced/backend/services/create-service.md#using-your-custom-service) documentation. @@ -122,7 +130,9 @@ If you’re on a Twilio trial make sure that the phone number you entered on che ![Twilio Dashboard](https://res.cloudinary.com/dza7lstvk/image/upload/v1668001219/Medusa%20Docs/Stripe/MXtQMiL_kb7kxe.png) -## What’s Next +--- -- Learn more about how [Notifications work in Medusa](../advanced/backend/notification/overview.md). +## See Also + +- [Notifications Overview](../advanced/backend/notification/overview.md). - Install the [Medusa admin](../admin/quickstart.mdx) for functionalities like Gift Cards creation, swaps, claims, order return requests, and more. diff --git a/docs/content/admin/development.md b/docs/content/admin/development.md index cd9763d11c..21e10cebdc 100644 --- a/docs/content/admin/development.md +++ b/docs/content/admin/development.md @@ -94,7 +94,7 @@ If your forked repository doesn’t have any conflicts with the changes from the --- -## What’s Next +## See Also -- Check out the [Admin API reference](/api/admin). -- Learn about [local development of the Medusa server](../usage/local-development.md). +- [Admin API reference](/api/admin). +- [Local development of the Medusa server](../usage/local-development.md). diff --git a/docs/content/admin/quickstart.mdx b/docs/content/admin/quickstart.mdx index ed99bae4e7..3462d3005e 100644 --- a/docs/content/admin/quickstart.mdx +++ b/docs/content/admin/quickstart.mdx @@ -26,6 +26,8 @@ node -v You can install Node from the [official website](https://nodejs.org/en/). +--- + ## Instant Deployment to Netlify Instead of manually following this guide to install then later deploy the Medusa Admin, you can deploy the Medusa Admin to Netlify with this button: @@ -34,6 +36,8 @@ Instead of manually following this guide to install then later deploy the Medusa Deploy to Netlify +--- + ## Install the Admin :::tip @@ -62,6 +66,8 @@ npm install negativeQuestion="Please describe the issue you faced." /> +--- + ## Test it Out Before running your Medusa admin, make sure that your Medusa server is running. @@ -100,6 +106,8 @@ You can use the email `admin@medusa-test.com` and password `supersecret` to log ::: +--- + ## Create a New Admin User To create a new admin user from the command line, run the following command in the directory holding your Medusa server: @@ -110,6 +118,8 @@ medusa user -e some@email.com -p some-password This will create a new user that you can use to log into your admin panel. +--- + ## Changing the Default Port The default port is set in `package.json` in the `dev` script: @@ -136,14 +146,18 @@ For more details about the Admin CORS configuration, check out the [Configure yo ::: +--- + ## Admin User Guide Medusa admin 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 Medusa admin and its features in the [User Guide](../user-guide/index.mdx). -## What’s Next +--- -- Learn how to [Customize Medusa Admin](./development.md) +## See Also + +- [Customize Medusa Admin](./development.md) - Install the [Next.js](../starters/nextjs-medusa-starter.mdx) or [Gatsby](../starters/gatsby-medusa-starter.mdx) storefront starters. -- [Learn how you can use `create-medusa-app` to install all of Medusa’s 3 components.](../usage/create-medusa-app.mdx) +- [Use `create-medusa-app` to install all of Medusa’s 3 components.](../usage/create-medusa-app.mdx) diff --git a/docs/content/advanced/admin/import-prices.mdx b/docs/content/advanced/admin/import-prices.mdx index 26f5d8aad2..35f0b4c7d6 100644 --- a/docs/content/advanced/admin/import-prices.mdx +++ b/docs/content/advanced/admin/import-prices.mdx @@ -15,6 +15,8 @@ Importing prices into a price list removes all existing prices in the price list ::: +--- + ## Prerequisites ### Medusa Components @@ -54,6 +56,8 @@ Before importing the prices, you must have a price list to import them to. You can use the [Create Price List](https://docs.medusajs.com/api/admin/#tag/Price-List/operation/PostPriceListsPriceList) endpoint, or follow the [how-to guide to learn how to create and manage price lists using the Admin API](../backend/price-lists/use-api.mdx). +--- + ## 1. Upload CSV File The first step is to upload the CSV file to import prices from. @@ -106,6 +110,8 @@ curl -L -X POST '/admin/uploads' \ This request returns an array of uploads. Each item in the array is an object that includes the properties `url` and `key`. You’ll need the `key` to import the prices next. +--- + ## 2. Create a Batch Job for Prices Import To start a new price import, you must create a batch job. @@ -192,6 +198,8 @@ If you don’t set `dry_run` or you set it to `false`, you don’t need to follo ::: +--- + ## (Optional) Retrieve Batch Job After creating the batch job, it will be pre-processed. At this point, the CSV file will be validated, and the number of prices to add are counted. @@ -253,6 +261,8 @@ Here’s an example of the `result` property: }, ``` +--- + ## 3. Confirm Batch Job A batch job can be confirmed only once the batch job has the status `pre_processed`. Once you confirm a batch job, the price import will start which will add prices to the price list @@ -305,7 +315,9 @@ After confirming the batch job, you can check the status while it is processing - If the status is `failed`, it means an error has occurred during the import. You can check the error in `result.errors`. - If the status is `completed`, it means the import has finished successfully. -## What’s Next 🚀 +--- -- Learn more about [Batch Jobs and how they work](../backend/batch-jobs/index.md). -- Check out the [Batch Jobs API Reference](https://docs.medusajs.com/api/admin/#tag/Batch-Job). \ No newline at end of file +## See Also + +- [Batch Jobs Overview](../backend/batch-jobs/index.md) +- [Batch Jobs API Reference](https://docs.medusajs.com/api/admin/#tag/Batch-Job) diff --git a/docs/content/advanced/admin/import-products.mdx b/docs/content/advanced/admin/import-products.mdx index c1ea4f9f05..68f99a0416 100644 --- a/docs/content/advanced/admin/import-products.mdx +++ b/docs/content/advanced/admin/import-products.mdx @@ -9,6 +9,8 @@ In this document, you’ll learn how to use the Admin APIs to bulk import produc Using Medusa’s [Batch Job Admin APIs](https://docs.medusajs.com/api/admin/#tag/Batch-Job), you can import products into your Medusa server. This will either add new products or update existing products. +--- + ## Prerequisites ### Medusa Components @@ -48,6 +50,8 @@ You must be an authenticated admin user before following along with the steps in You can learn more about [authenticating as an admin user in the API reference](/api/admin/#section/Authentication). +--- + ## 1. Upload CSV File The first step is to upload the CSV file that you want to import products. @@ -100,6 +104,8 @@ curl -L -X POST '/admin/uploads' \ This request returns an array of uploads. Each item in the array is an object that includes the properties `url` and `key`. You’ll need the `key` to import the products next. +--- + ## 2. Create a Batch Job for Product Import To start a new product import, you must create a batch job. @@ -180,6 +186,8 @@ If you don’t set `dry_run` or you set it to `false`, you don’t need to follo ::: +--- + ## (Optional) Retrieve Batch Job After creating the batch job, it will be pre-processed. At this point, the CSV file will be validated, and the number of products to add and update, or that are rejected are counted. @@ -241,6 +249,8 @@ Here’s an example of the `result` property: }, ``` +--- + ## 3. Confirm Batch Job A batch job can be confirmed only once the batch job has the status `pre_processed`. Once you confirm a batch job, the product import will start which will create or update products on your server. @@ -293,7 +303,9 @@ After confirming the batch job, you can check the status while it is processing - If the status is `failed`, it means an error has occurred during the import. You can check the error in `result.errors`. - If the status is `completed`, it means the import has finished successfully. -## What’s Next +--- -- Learn more about [Batch Jobs and how they work](../backend/batch-jobs/index.md). -- Check out the [Batch Jobs API Reference](https://docs.medusajs.com/api/admin/#tag/Batch-Job). +## See Also + +- [Batch Jobs Overview](../backend/batch-jobs/index.md) +- [Batch Jobs API Reference](https://docs.medusajs.com/api/admin/#tag/Batch-Job) diff --git a/docs/content/advanced/admin/manage-discounts.mdx b/docs/content/advanced/admin/manage-discounts.mdx index 0e31308b75..16631968fa 100644 --- a/docs/content/advanced/admin/manage-discounts.mdx +++ b/docs/content/advanced/admin/manage-discounts.mdx @@ -29,6 +29,8 @@ You can use Medusa’s Admin APIs to achieve more functionalities as well. Check ::: +--- + # Prerequisites ### Medusa Components @@ -47,6 +49,8 @@ You must be an authenticated admin user before following along with the steps in You can learn more about [authenticating as an admin user in the API reference](/api/admin/#section/Authentication). +--- + ## Create a Discount You can create a discount by sending a request to the [Create Discount](/api/admin/#tag/Discount/operation/PostDiscounts) endpoint: @@ -135,6 +139,8 @@ This request accepts [many request-body parameters](/api/admin/#tag/Discount/ope This request returns the full `discount` object. +--- + ## Update Discount You can update any of the discount’s information, configurations, and conditions by sending a request to the [Update Discount](/api/admin/#tag/Discount/operation/PostDiscountsDiscount) endpoint. @@ -197,6 +203,8 @@ You can check the [API reference](/api/admin/#tag/Discount/operation/PostDiscoun This updates the discount’s information and returns the full updated `discount` object in the response. +--- + ## Manage Conditions ### Create a Condition @@ -441,6 +449,8 @@ This request accepts as a path parameter the discount ID and the condition ID. It returns the `discount` object in the response. +--- + ## Delete Discount You can delete a discount by sending a request to the [Delete Discount](/api/admin/#tag/Discount/operation/DeleteDiscountsDiscount) endpoint: @@ -488,7 +498,9 @@ It returns in the response the following fields: - `object`: A string indicating the type of object deleted. By default, its value is `discount`. - `deleted`: A boolean value indicating whether the discount was deleted or not. -## What’s Next +--- -- Check out more [Admin Discount APIs in the API reference](/api/admin/#tag/Discount). -- Learn how you can [use Discounts on the storefront](../storefront/use-discounts-in-checkout.mdx). +## See Also + +- [Discounts API reference](/api/admin/#tag/Discount) +- [Use Discounts on the storefront](../storefront/use-discounts-in-checkout.mdx) diff --git a/docs/content/advanced/admin/manage-regions.mdx b/docs/content/advanced/admin/manage-regions.mdx index a025618d92..0fdca9b319 100644 --- a/docs/content/advanced/admin/manage-regions.mdx +++ b/docs/content/advanced/admin/manage-regions.mdx @@ -397,7 +397,7 @@ This request requires the region ID as a path parameter. It deletes the region a --- -## What’s Next +## See Also -- Learn more about [Regions’ architecture](../backend/regions/overview.md). -- Learn [how to use Regions on the storefront](../storefront/use-regions.mdx). \ No newline at end of file +- [Regions Overview](../backend/regions/overview.md) +- [Use Regions on the storefront](../storefront/use-regions.mdx) \ No newline at end of file diff --git a/docs/content/advanced/admin/order-edit.mdx b/docs/content/advanced/admin/order-edit.mdx index 89b2bd7fbd..b99697912e 100644 --- a/docs/content/advanced/admin/order-edit.mdx +++ b/docs/content/advanced/admin/order-edit.mdx @@ -605,7 +605,9 @@ Check out what other parameters can be sent in the [API reference](/api/admin/#t It returns in the response the full Refund object. -## What’s Next +--- -- Learn how to [handle order edits on the storefront](../storefront/handle-order-edits). -- Check out more [order edit endpoints in the API reference](/api/admin/#tag/OrderEdit). +## See Also + +- [Handle order edits on the storefront](../storefront/handle-order-edits). +- [Order Edits API reference](/api/admin/#tag/OrderEdit). diff --git a/docs/content/advanced/admin/use-customergroups-api.mdx b/docs/content/advanced/admin/use-customergroups-api.mdx index 0e615f5816..c00f77b8d4 100644 --- a/docs/content/advanced/admin/use-customergroups-api.mdx +++ b/docs/content/advanced/admin/use-customergroups-api.mdx @@ -468,7 +468,7 @@ When you create or update a price list, you can specify one or more customer gro --- -## What’s Next +## See Also -- Learn more about [Customer Groups](../backend/customer-groups/index.md). -- Learn about [how to use Sales Channels](../backend/sales-channels/manage-admin.mdx). \ No newline at end of file +- [Customer Groups Overview](../backend/customer-groups/index.md). +- [Use Sales Channels Admin APIs](../backend/sales-channels/manage-admin.mdx). \ No newline at end of file diff --git a/docs/content/advanced/backend/batch-jobs/create.md b/docs/content/advanced/backend/batch-jobs/create.md index f42ab354cc..7ace8e2c91 100644 --- a/docs/content/advanced/backend/batch-jobs/create.md +++ b/docs/content/advanced/backend/batch-jobs/create.md @@ -17,6 +17,8 @@ Batch jobs can be used to perform long tasks in the background of your Medusa se This documentation helps you learn how to create a batch job strategy. The batch job strategy used in this example changes the status of all draft products to `published`. +--- + ## Prerequisites ### Medusa Components @@ -31,12 +33,16 @@ Redis is required for batch jobs to work. Make sure you [install Redis](../../. If you use SQLite during your development, it’s highly recommended that you use PostgreSQL when working with batch jobs. Learn how to [install PostgreSQL](../../../tutorial/0-set-up-your-development-environment.mdx#postgresql) and [configure it with your Medusa server](../../../usage/configurations.md#postgresql-configurations). +--- + ## 1. Create a File A batch job strategy is essentially a class defined in a TypeScript or JavaScript file. You should create this file in `src/strategies`. Following the example used in this documentation, create the file `src/strategies/publish.ts`. +--- + ## 2. Create Class Batch job strategies must extend the abstract class `AbstractBatchJobStrategy` and implement its abstract methods. @@ -63,6 +69,8 @@ class PublishStrategy extends AbstractBatchJobStrategy { export default PublishStrategy ``` +--- + ## 3. Define Required Properties A batch job strategy class must have two static properties: the `identifier` and `batchType` properties. The `identifier` must be a unique string associated with your batch job strategy, and `batchType` must be the batch job's type. @@ -80,6 +88,8 @@ class PublishStrategy extends AbstractBatchJobStrategy { } ``` +--- + ## 4. Define Methods ### (Optional) prepareBatchJobForProcessing @@ -222,6 +232,8 @@ protected async handleProcessingError(batchJobId: string, err: unknown, resul } ``` +--- + ## 5. Run Build Command After you create the batch job and before testing it out, you must run the build command in the directory of your Medusa server: @@ -230,6 +242,8 @@ After you create the batch job and before testing it out, you must run the build npm run build ``` +--- + ## Test your Batch Job Strategy This section covers how to test and use your batch job strategy. Make sure to start your server first: @@ -410,7 +424,9 @@ The batch job will start processing afterward. Based on the batch job strategy i You can [retrieve the batch job](#optional-retrieve-batch-job) at any given point to check its status. -## What’s Next +--- -- Learn more about [batch jobs](./index.md). -- Learn how to [import products using the Admin API](../../admin/import-products.mdx). +## See Also + +- [Batch Jobs Overview](./index.md). +- [Import products using the Admin API](../../admin/import-products.mdx). diff --git a/docs/content/advanced/backend/batch-jobs/customize-import.md b/docs/content/advanced/backend/batch-jobs/customize-import.md index c729f0f5a2..e1a656fa4b 100644 --- a/docs/content/advanced/backend/batch-jobs/customize-import.md +++ b/docs/content/advanced/backend/batch-jobs/customize-import.md @@ -8,6 +8,8 @@ Product Import Strategy is essentially a batch job strategy. Medusa provides the Although this documentation specifically targets import strategies, you can use the same steps to overwrite any batch job strategy in Medusa, including export strategies. +--- + ## Prerequisites ### Medusa Components @@ -22,6 +24,8 @@ Redis is required for batch jobs to work. Make sure you [install Redis](../../. If you use SQLite during your development, it’s highly recommended that you use PostgreSQL when working with batch jobs. Learn how to [install PostgreSQL](../../../tutorial/0-set-up-your-development-environment.mdx#postgresql) and [configure it with your Medusa server](../../../usage/configurations.md#postgresql-configurations). +--- + ## Overwrite Batch Job Strategy The steps required for overwriting a batch job strategy are essentially the same steps required to create a batch job strategy with a minor difference. For that reason, this documentation does not cover the basics of a batch job strategy. @@ -103,13 +107,17 @@ Specifically, since you create batch jobs using the [Create Batch Job](https://d If you overwrote the import functionality, you can follow [these steps to learn how to import products using the Admin APIs](../../admin/import-products.mdx). +--- + ## Create Custom Batch Job Strategy If you don’t want to overwrite Medusa’s batch job strategy, you can create a custom batch job strategy with a different `batchType` value. Then, use that type when you send a request to [Create a Batch Job](https://docs.medusajs.com/api/admin/#tag/Batch-Job). For more details on creating custom batch job strategies, please check out the [Create Batch Job Strategy documentation](create.md). +--- + ## What’s Next -- Learn more about [batch jobs](./index.md). -- Learn [how to use the Import Product APIs](../../admin/import-products.mdx). +- [Batch Jobs Overview](./index.md). +- [Use the Import Product APIs](../../admin/import-products.mdx). diff --git a/docs/content/advanced/backend/batch-jobs/index.md b/docs/content/advanced/backend/batch-jobs/index.md index c2e4122684..caf20ccd22 100644 --- a/docs/content/advanced/backend/batch-jobs/index.md +++ b/docs/content/advanced/backend/batch-jobs/index.md @@ -26,6 +26,8 @@ A batch job is stored in the database as a [BatchJob](https://docs.medusajs.com/ - `count`: A number that includes the total count of records related to the operation. For example, in the case of product exports, it is used to indicate the total number of products exported. - `advancement_count`: A number that indicates the number of records processed so far. Can be helpful when retrying a batch job. +--- + ## What are Batch Job Strategies Batch jobs are handled by batch job strategies. A batch job strategy is a class that extends the `AbstractBatchJobStrategy` abstract class and implements the methods defined in that class to handle the different states of a batch job. @@ -34,6 +36,8 @@ A batch job strategy must implement the necessary methods to handle the preparat When you create a batch job strategy, the `batchType` class property indicates the batch job types this strategy handles. Then, when you create a new batch job, you set the batch job’s type to the value of `batchType` in your strategy. +--- + ## How Batch Jobs Work A batch job’s flow from creation to completion is: @@ -56,6 +60,8 @@ If the batch job fails at any point in this flow, its status is changed to `fail ![Flowchart summarizing the batch job's flow from creation to completion](https://res.cloudinary.com/dza7lstvk/image/upload/v1668001632/Medusa%20Docs/Diagrams/Qja0kAz_ns4vm8.png) +--- + ## What’s Next -- Learn about the [Batch Job’s events](../subscribers/events-list.md#batch-jobs-events). +- [Batch Job’s Events Reference](../subscribers/events-list.md#batch-jobs-events). diff --git a/docs/content/advanced/backend/customer-groups/index.md b/docs/content/advanced/backend/customer-groups/index.md index a9349812bc..6823503e2e 100644 --- a/docs/content/advanced/backend/customer-groups/index.md +++ b/docs/content/advanced/backend/customer-groups/index.md @@ -24,7 +24,7 @@ A customer group is stored in the database as a [CustomerGroup](../../../refere Similar to all entities in Medusa, you can use the `metadata` object attribute to store any custom data you want. For example, you can add some flag or tag to the customer group for a custom use case: -```jsx noReport +```js noReport metadata: { is_seller: true } @@ -54,7 +54,7 @@ The relation between the `PriceList` and `CustomerGroup` entities is available o --- -## What’s Next +## See Also -- Learn [how to manage customer groups using the Admin APIs](../../admin/use-customergroups-api.mdx). -- Learn more about [Price Lists and how they work](../price-lists/index.md). +- [Manage customer groups using the Admin APIs](../../admin/use-customergroups-api.mdx). +- [Price Lists Overview](../price-lists/index.md). diff --git a/docs/content/advanced/backend/dependency-container/index.md b/docs/content/advanced/backend/dependency-container/index.md index d5966b7b44..04ab45f43d 100644 --- a/docs/content/advanced/backend/dependency-container/index.md +++ b/docs/content/advanced/backend/dependency-container/index.md @@ -26,6 +26,8 @@ When you run the Medusa server, a container of the type `MedusaContainer` is cre The server then registers all important resources in the container, which makes them accessible in classes and endpoints. +--- + ## Registered Resources The Medusa server scans the core Medusa package, plugins, and your files in the `dist` directory and registers the following resources: @@ -550,6 +552,8 @@ Its camel-case name. +--- + ## Loading Resources This section covers how to load resources that the Medusa server registers when it starts running. @@ -560,7 +564,7 @@ To load resources, such as services, in endpoints, use the `req.scope.resolve` f For example: -```typescript +```ts const logger = req.scope.resolve('logger'); ``` @@ -572,7 +576,7 @@ In classes such as services, strategies, or subscribers, you can load resources For example: -```typescript +```ts import { OrderService } from '@medusajs/medusa'; class OrderSubscriber { @@ -584,7 +588,9 @@ class OrderSubscriber { } ``` -## What’s Next +--- -- Learn [how to create services](../services/create-service.md). -- Learn [how to create subscribers](../subscribers/create-subscriber.md). +## See Also + +- [Create services](../services/create-service.md). +- [Create subscribers](../subscribers/create-subscriber.md). diff --git a/docs/content/advanced/backend/discounts/index.md b/docs/content/advanced/backend/discounts/index.md index 2a1b0d7d9b..094f96c43e 100644 --- a/docs/content/advanced/backend/discounts/index.md +++ b/docs/content/advanced/backend/discounts/index.md @@ -98,7 +98,7 @@ Based on the value of `type`, one of the following relations can be used to retr --- -## What’s Next +## See Also -- Learn [how to create a discount using the admin APIs](../../admin/manage-discounts.mdx) -- Learn [how to use discounts on the storefront](../../storefront/use-discounts-in-checkout.mdx) +- [Create a discount using the admin APIs](../../admin/manage-discounts.mdx) +- [Use discounts on the storefront](../../storefront/use-discounts-in-checkout.mdx) diff --git a/docs/content/advanced/backend/endpoints/add.md b/docs/content/advanced/backend/endpoints/add.md index 86a204143b..5e7b55b26b 100644 --- a/docs/content/advanced/backend/endpoints/add.md +++ b/docs/content/advanced/backend/endpoints/add.md @@ -6,6 +6,8 @@ In this document, you’ll learn how to create endpoints in your Medusa server. Custom endpoints reside under the `src/api` directory in your Medusa Backend. They're defined in a TypeScript or JavaScript file that is named `index` (for example, `index.ts`). This file should export a function that returns an Express router. +--- + ## Implementation To create a new endpoint, start by creating a new file in `src/api` called `index.ts`. At its basic format, `index.ts` should look something like this: @@ -42,6 +44,8 @@ By Medusa’s conventions: You can also create endpoints that don't reside under these two prefixes, similar to the `hello` endpoint in the previous example. +--- + ## CORS Configuration If you’re adding a storefront or admin endpoint and you want to access these endpoints from the storefront or Medusa admin, you need to pass your endpoints Cross-Origin Resource Origin (CORS) options using the `cors` package. @@ -94,6 +98,8 @@ router.get("/admin/hello", cors(corsOptions), (req, res) => { }) ``` +--- + ## Create Multiple Endpoints ### Same File @@ -185,6 +191,8 @@ export default () => { } ``` +--- + ## Protected Routes Protected routes are routes that should be accessible by logged-in customers or users only. @@ -238,6 +246,8 @@ router.get("/admin/products/count", cors(corsOptions), authenticate(), async (re Now, only authenticated users can access this endpoint. +--- + ## Use Services Services in Medusa bundle a set of functionalities into one class. Then, you can use that class anywhere in your backend. For example, you can use the `ProductService` to retrieve products or perform operations like creating or updating a product. @@ -260,6 +270,8 @@ router.get("/admin/products/count", cors(corsOptions), authenticate(), (req, res The `productService` has a `count` method that returns a Promise. This Promise resolves to the count of the products. You return a JSON of the product count. +--- + ## Building Files Custom endpoints must be transpiled and moved to the `dist` directory. This happens when you run your server using `medusa develop` and while it’s running, and when you run the following command: @@ -268,7 +280,10 @@ Custom endpoints must be transpiled and moved to the `dist` directory. This happ npm run build ``` -## What’s Next +--- -- Check out the available [Admin](https://docs.medusajs.com/api/admin/) and [Storefront](https://docs.medusajs.com/api/store/) APIs. -- Learn how to create a [Service](./../services/create-service.md). +## See Also + +- [Storefront API Reference](/api/store) +- [Admin API Reference](/api/admin) +- [Create a Service](./../services/create-service.md). diff --git a/docs/content/advanced/backend/entities/index.md b/docs/content/advanced/backend/entities/index.md index 89d63127e6..3410df6523 100644 --- a/docs/content/advanced/backend/entities/index.md +++ b/docs/content/advanced/backend/entities/index.md @@ -69,6 +69,8 @@ Be careful with your file names as it can cause unclear errors in Typeorm. Make ::: +--- + ## Access a Custom Entity :::note @@ -125,8 +127,10 @@ To delete soft-deletable entities that extend the `SoftDeletableEntity` class, y await postRepository.softDelete(post.id); ``` -## What’s Next +--- -- Check out Medusa's entities in the [Entities' reference](../../../references/entities/classes/Address.md). -- Learn about [migrations](../migrations/overview.md). -- Learn more about [Services](../services/create-service.md) and how to use them. +## See Also + +- [Entities' reference](../../../references/entities/classes/Address.md) +- [Migrations Overview](../migrations/overview.md) +- [Create a Services](../services/create-service.md) diff --git a/docs/content/advanced/backend/entities/overview.md b/docs/content/advanced/backend/entities/overview.md index 8b32de6193..550e80da20 100644 --- a/docs/content/advanced/backend/entities/overview.md +++ b/docs/content/advanced/backend/entities/overview.md @@ -10,13 +10,17 @@ Aside from Medusa’s core entities, you can also create your own entities to us Entities are TypeScript files and they are based on [Typeorm’s Entities](https://typeorm.io/entities) and use Typeorm decorators. +--- + ## Base Entities All entities must extend either the `BaseEntity` or `SoftDeletableEntity` classes. The `BaseEntity` class holds common columns including the `id`, `created_at`, and `updated_at` columns. The `SoftDeletableEntity` class extends the `BaseEntity` class and adds another column `deleted_at`. If an entity can be soft deleted, meaning that a row in it can appear to the user as deleted but still be available in the database, it should extend `SoftDeletableEntity`. -## What's Next +--- -- Learn [how to create an entity](./index.md). -- Check out Medusa's entities in the [Entities' reference](../../../references/entities/classes/Address.md). \ No newline at end of file +## See Also + +- [Create an entity](./index.md) +- [Entities' reference](../../../references/entities/classes/Address.md) \ No newline at end of file diff --git a/docs/content/advanced/backend/feature-flags/toggle.md b/docs/content/advanced/backend/feature-flags/toggle.md index a1f5a6904c..9fb723f860 100644 --- a/docs/content/advanced/backend/feature-flags/toggle.md +++ b/docs/content/advanced/backend/feature-flags/toggle.md @@ -8,6 +8,8 @@ Feature flags are used in Medusa to guard beta features that aren’t ready for To use these beta features, you must enable their feature flags. +--- + ## Available Feature Flags You can view a list of available feature flags that you can toggle in [the Medusa GitHub mono-repository](https://github.com/medusajs/medusa/tree/master/packages/medusa/src/loaders/feature-flags). In each feature flag file, you can find the default value of the feature flag, its name, environment variable name, and more. @@ -18,6 +20,8 @@ If a feature flag is enabled/disabled by default, you don’t need to manually e ::: +--- + ## Enable Feature Flags :::caution @@ -73,6 +77,8 @@ You can learn more about migrations in this documentation. ::: +--- + ## Disable Feature Flags Disabling feature flags follows the same process as enabling the feature flags. All you have to do is change the value in the environment variables or the server settings to `false`. @@ -85,7 +91,9 @@ If you had the feature flag previously enabled, and you want to disable this fea You can follow [this documentation to learn how to revert the last migration you ran](https://docs.medusajs.com/cli/reference#migrations). -## What’s Next +--- -- Learn more about [Migrations](../migrations/overview.md). -- Learn how to [configure your Medusa server](../../../usage/configurations.md). +## See Also + +- [Migrations Overview](../migrations/overview.md). +- [Configure your Medusa server](../../../usage/configurations.md). diff --git a/docs/content/advanced/backend/migrations/index.md b/docs/content/advanced/backend/migrations/index.md index f555afdbf5..784bb8a317 100644 --- a/docs/content/advanced/backend/migrations/index.md +++ b/docs/content/advanced/backend/migrations/index.md @@ -20,12 +20,16 @@ You can alternatively use Typeorm's `generate` command to generate a Migration f ::: +--- + ## Write Migration File The migration file contains the necessary commands to create the database columns, foreign keys, and more. You can learn more about writing the migration file in You can learn more about writing migrations in [Typeorm’s Documentation](https://typeorm.io/migrations). +--- + ## Build Files Before you can run the migrations you need to run the build command to transpile the TypeScript files to JavaScript files: @@ -34,6 +38,8 @@ Before you can run the migrations you need to run the build command to transpile npm run build ``` +--- + ## Run Migration The last step is to run the migration with the command detailed earlier @@ -44,6 +50,8 @@ medusa migrations run If you check your database now you should see that the change defined by the migration has been applied successfully. +--- + ## What’s Next -- Learn more about [setting up your development server](../../../tutorial/0-set-up-your-development-environment.mdx). +- [Set up your development server](../../../tutorial/0-set-up-your-development-environment.mdx). diff --git a/docs/content/advanced/backend/migrations/overview.md b/docs/content/advanced/backend/migrations/overview.md index eaee22ae25..743991da6d 100644 --- a/docs/content/advanced/backend/migrations/overview.md +++ b/docs/content/advanced/backend/migrations/overview.md @@ -22,6 +22,8 @@ Migrations are used to apply changes to the database schema. However, there are ::: +--- + ## How to Run Migrations Migrations in Medusa can be done in one of two ways: @@ -48,7 +50,9 @@ npm run seed This will use the underlying `seed` command provided by Medusa's CLI to seed your database with data from the file `data/seed.json` on your Medusa server. -## What's Next +--- -- Learn [how to create a migration](index.md) -- Learn more about [setting up your development server](../../../tutorial/set-up-your-development-environment). +## See Also + +- [Create a migration](index.md) +- [Set up your development environment](../../../tutorial/set-up-your-development-environment) diff --git a/docs/content/advanced/backend/notification/how-to-create-notification-provider.md b/docs/content/advanced/backend/notification/how-to-create-notification-provider.md index f6fe9a28b5..3ca92225fd 100644 --- a/docs/content/advanced/backend/notification/how-to-create-notification-provider.md +++ b/docs/content/advanced/backend/notification/how-to-create-notification-provider.md @@ -14,6 +14,8 @@ Before you start creating a Notification Provider, you need to install a [Medusa You also need to [setup Redis](../../../tutorial/0-set-up-your-development-environment.mdx#redis) and [configure it with the Medusa server](../../../usage/configurations.md#redis). +--- + ## Create a Notification Provider Creating a Notification Provider is as simple as creating a TypeScript or JavaScript file in `src/services`. The name of the file is the name of the provider (for example, `sendgrid.ts`). A Notification Provider is essentially a Service that extends the `AbstractNotificationService` from `@medusajs/medusa`. @@ -205,6 +207,8 @@ The `to` and `data` properties are used in the `NotificationService` in Medusa ::: +--- + ## Create a Subscriber After creating your Notification Provider Service, you must create a Subscriber that registers this Service as a notification handler of events. @@ -235,6 +239,8 @@ Notice that the value of the `identifier` static property defined in the `EmailS ::: +--- + ## Test Sending Notifications with your Notification Provider Make sure you've configured Redis with your Medusa server as explained in the Prerequisites section and that the Redis service is running. @@ -255,6 +261,8 @@ If you don’t have a storefront installed you can get started with either the [ After placing an order, you can see in your console the message “Notification Sent”. If you added your own notification sending logic, you should receive an email or alternatively the type of notification you’ve set up. +--- + ## Test Resending Notifications with your Notification Provider To test resending a notification, first, retrieve the ID of the notification you just sent using the [List Notifications admin endpoint](https://docs.medusajs.com/api/admin/#tag/Notification/operation/GetNotifications). You can pass as a body parameter the `to` or `event_name` parameters to filter out the notification you just sent. @@ -273,9 +281,12 @@ Then, send a request to the [Resend Notification](https://docs.medusajs.com/api/ This request returns the same notification object as the List Notifications endpoint, but it now has a new object in the `resends` array. This is the resent notification. If you supplied a `to` parameter in the request body, you should see its value in the `to` property of the resent notification object. -## What’s Next +--- -- Check out the [list of events](../subscribers/events-list.md) you can listen to. -- Check out the [SendGrid](../../../add-plugins/sendgrid.mdx) plugin for easy integration of email notifications. -- Learn how to [create your own plugin](../plugins/create.md). -- Learn more about [Subscribers](../subscribers/create-subscriber.md) and [Services](../services/create-service.md). +## See Also + +- [Events reference](../subscribers/events-list.md) +- [SendGrid Plugin](../../../add-plugins/sendgrid.mdx) +- [Create a Subscriber](../subscribers/create-subscriber.md) +- [Create a Service](../services/create-service.md). +- [Create a Plugin](../plugins/create.md). diff --git a/docs/content/advanced/backend/notification/overview.md b/docs/content/advanced/backend/notification/overview.md index 4183049aba..dd43920783 100644 --- a/docs/content/advanced/backend/notification/overview.md +++ b/docs/content/advanced/backend/notification/overview.md @@ -8,6 +8,8 @@ Medusa provides a Notification API to mainly handle sending and resending notifi The Notification architecture is made up of two main components: the Notification Provider and the Notification. Simply put, the Notification Provider handles the sending and resending of a Notification. +--- + ## Notification Provider A Notification Provider is a provider that handles sending and resending of notifications. You can either create and integrate your own provider or install a Notification Provider through a third-party plugin. @@ -32,6 +34,8 @@ The `NotificationProvider` entity only has 2 attributes: `id` and `is_installed` If you installed a Notification provider and then removed the Service files or plugin that registered the Notification Provider, the Notification Provider remains in your database, but the value of the `is_installed` field changes to `false`. +--- + ## Notification A notification is a form of an alert sent to the customers or users to inform them of an action that has occurred. For example, if an order is placed, the notification, in this case, can be an email that confirms their order and lists the order details. @@ -67,6 +71,8 @@ You can also access the specific resource using the `resource_id` property, whic The `Notification` entity also includes properties related to the receiver of the Notification. In case the receiver is a customer, the `customer_id` property is used to identify which customer. +--- + ## Automating Flows with Notifications With Medusa you can create notifications as a reaction to a wide spectrum of events, allowing you to automate communication and processes. @@ -78,10 +84,13 @@ An example of a flow that can be implemented using Medusa's Notification API is - The customer returns the items triggering the `return.recieved` event. - The Notification Provider listens to the `return.received` event and sends an email to the customer with confirmation that their items have been received and that a refund has been issued. -## What’s Next +--- + +## See Also + +- [Create a Notification Provider](how-to-create-notification-provider.md) +- [Events reference](../subscribers/events-list.md) +- [SendGrid Plugin](../../../add-plugins/sendgrid.mdx) +- [Subscribers Overview](../subscribers/create-subscriber.md) +- [Services Overview](../services/create-service.md) -- Learn how to [create your own Notification Provider](how-to-create-notification-provider.md). -- Check out the [list of events](../subscribers/events-list.md) in Medusa. -- Check the [`NotificationService`](../../../references/services/classes/NotificationService.md) API reference for more details on how it works. -- Check out the [SendGrid](../../../add-plugins/sendgrid.mdx) Notification plugin. -- Learn more about [Subscribers](../subscribers/create-subscriber.md) and [Services](../services/create-service.md) in Medusa. diff --git a/docs/content/advanced/backend/payment/how-to-create-payment-provider.md b/docs/content/advanced/backend/payment/how-to-create-payment-provider.md index d27529626f..ba1af5059a 100644 --- a/docs/content/advanced/backend/payment/how-to-create-payment-provider.md +++ b/docs/content/advanced/backend/payment/how-to-create-payment-provider.md @@ -42,6 +42,8 @@ These methods are used at different points in the Checkout flow as well as when ![Checkout Flow - Payment](https://res.cloudinary.com/dza7lstvk/image/upload/v1668001750/Medusa%20Docs/Diagrams/WeDr0ph_idcrir.jpg) +--- + ## Create a Payment Provider The first step to create a payment provider is to create a JavaScript or TypeScript file in `src/services`. The file's name should be the name of the payment provider. @@ -414,6 +416,8 @@ async cancelPayment(payment: Payment): Promise { } ``` +--- + ## Optional Methods ### retrieveSavedMethods @@ -457,7 +461,9 @@ async retrieveSavedMethods(customer: Customer): Promise { } ``` -## What’s Next +--- -- Check out the Payment Providers for [Stripe](https://github.com/medusajs/medusa/tree/2e6622ec5d0ae19d1782e583e099000f0a93b051/packages/medusa-payment-stripe) and [PayPal](https://github.com/medusajs/medusa/tree/2e6622ec5d0ae19d1782e583e099000f0a93b051/packages/medusa-payment-paypal) for implementation examples. -- Learn more about the [frontend checkout flow](./../../storefront/how-to-implement-checkout-flow.mdx). +## See Also + +- Implementation Examples: [Stripe](https://github.com/medusajs/medusa/tree/2e6622ec5d0ae19d1782e583e099000f0a93b051/packages/medusa-payment-stripe) and [PayPal](https://github.com/medusajs/medusa/tree/2e6622ec5d0ae19d1782e583e099000f0a93b051/packages/medusa-payment-paypal) payment providers. +- [Implement checkout flow on the storefront](./../../storefront/how-to-implement-checkout-flow.mdx). diff --git a/docs/content/advanced/backend/payment/overview.md b/docs/content/advanced/backend/payment/overview.md index 94b0f58fb8..cfea8ef5b9 100644 --- a/docs/content/advanced/backend/payment/overview.md +++ b/docs/content/advanced/backend/payment/overview.md @@ -14,6 +14,8 @@ In Medusa, there are 3 main components in the payment architecture: Payment Prov An important part in the Payment architecture to understand is the **Idempotency Key**. It’s a unique value that’s generated for a cart and is used to retry payments during checkout if they fail. +--- + ## Payment Provider A Payment Provider in Medusa is a method to handle payments in selected regions. It is not associated with a cart, customer, or order in particular. It provides the necessary implementation to create Payment Sessions and Payments, as well as authorize and capture payments, among other functionalities. @@ -42,6 +44,8 @@ It’s important to choose a payment provider in the list of payment providers i The [`PaymentProvider`](../../../references/entities/classes/PaymentProvider.md) entity only has 2 attributes: `is_installed` to indicate if the payment provider is installed and its value is a boolean; and `id` which is the unique identifier that you define in the Payment Provider service. +--- + ## Payment Session Payment Sessions are linked to a customer’s cart. Each Payment Session is associated with a payment provider that is available in the customer cart’s region. @@ -80,6 +84,8 @@ The `status` attributes indicates the current status of the Payment Session. It These statuses are important in the checkout flow to determine the current step the customer is at and which action should come next. For example, if there is an attempt to place the order but the status of the Payment Session is not `authorized`, an error will be thrown. +--- + ## Payment A Payment is used to represent the amount authorized for a customer’s purchase. It is associated with the order placed by the customer and will be used after that for all operations related to the order’s payment such as capturing or refunding the payment. @@ -104,6 +110,8 @@ Similar to `PaymentSession`, `Payment` has a `data` attribute which is an objec Additionally, `Payment` has the `captured_at` date-time attribute which is filled when the payment has been captured, and a `canceled_at` date-time attribute which is filled when the order has been canceled. +--- + ## Idempotency Key An Idempotency Key is a unique key associated with a cart. It is generated at the last step of checkout before authorization of the payment is attempted. @@ -118,7 +126,9 @@ If then the request is interrupted for any reason or the payment fails, the clie This prevents any payment issues from occurring with the customers and allows for secure retries of failed payments or interrupted connections. -## What’s Next +--- -- [Check out how the checkout flow is implemented on the frontend.](./../../storefront/how-to-implement-checkout-flow.mdx) -- Check out payment plugins like [Stripe](../../../add-plugins/stripe.md), [Paypal](/add-plugins/paypal), and [Klarna](../../../add-plugins/klarna.md). +## See Also + +- [Create a Payment Provider](./how-to-create-payment-provider.md) +- [Implement the checkout flow in the storefront](./../../storefront/how-to-implement-checkout-flow.mdx) diff --git a/docs/content/advanced/backend/plugins/create.md b/docs/content/advanced/backend/plugins/create.md index c520e4c96a..3824f47dea 100644 --- a/docs/content/advanced/backend/plugins/create.md +++ b/docs/content/advanced/backend/plugins/create.md @@ -16,6 +16,8 @@ If you run into any errors while installing the CLI tool, check out the [trouble ::: +--- + ## Initialize Project The recommended way to create a plugin is using the Medusa CLI. Run the following command to create a new Medusa project: @@ -28,6 +30,8 @@ Where `medusa-plugin-custom` is the name of the plugin you’re creating. In Med By convention, all plugin names start with `medusa` followed by a descriptive name of what the plugin does. For example, the Stripe plugin is named `medusa-payment-stripe`. +--- + ## Changes to package.json ### Rename Project Name @@ -145,6 +149,8 @@ npm install --save-dev cross-env - `repository`: The repository that holds your plugin’s codebase. - `keywords`: This should hold the keywords that are related to your plugin. It’s recommended that all plugins use the keywords `medusa-plugin` or `medusa`. +--- + ## Develop your Plugin Now, You can start developing your plugin. This can include adding services, endpoints, entities, or anything that's relevant to your plugin. @@ -196,6 +202,8 @@ This guide doesn't cover how to create different files and components. If you’ - How to [create an entity](./../entities/index.md) - How to [create a migration](../migrations/index.md) +--- + ## Add Plugin Configuration Plugins often allow developers that will later use them to enter their own configuration. For example, you can allow developers to specify the API key of a service you’re integrating. @@ -248,6 +256,8 @@ Make sure to include in the README of your plugin the configurations that can be ::: +--- + ## Test Your Plugin While you develop your plugin, you’ll need to test it on an actual Medusa server. This can be done by using the [npm link](https://docs.npmjs.com/cli/v8/commands/npm-link) command. @@ -354,6 +364,8 @@ It is safe to ignore any `cross-env: command not found` error you may receive. ::: +--- + ## NPM Ignore File Not all files that you use while developing your plugin are necessary to be published. @@ -387,6 +399,8 @@ medusa-db.sql develop.sh ``` +--- + ## Publish Plugin Once you’re done developing your plugin you can publish the package on NPM’s registry so that other developers can benefit from it and use it. @@ -439,6 +453,8 @@ Then, publish the new update: npm publish ``` +--- + ## Add Plugin to Medusa’s Repository All officially-supported plugins are available in the [`packages` directory of the Medusa GitHub repository](https://github.com/medusajs/medusa/tree/master/packages). @@ -451,6 +467,8 @@ Before contributing to the Medusa repository, please check out the [contribution ::: +--- + ## Install a Plugin To install any published plugin, you can run the following command on any Medusa server project: @@ -459,8 +477,10 @@ To install any published plugin, you can run the following command on any Medusa npm install medusa-plugin-custom ``` -## What’s Next +--- -- Check out [available Services in Medusa](references/services/../../../../../references/services/classes/AuthService.md) that you can use in your plugin. -- Check out [available events](../subscribers/events-list.md) that you can listen to in Subscribers. -- Check out [available official plugins](https://github.com/medusajs/medusa/tree/master/packages). +## See Also + +- [Available official plugins](https://github.com/medusajs/medusa/tree/master/packages) +- [Services reference](references/services/../../../../../references/services/classes/AuthService.md) +- [Events reference](../subscribers/events-list.md) diff --git a/docs/content/advanced/backend/plugins/overview.md b/docs/content/advanced/backend/plugins/overview.md index aaad259683..2a3b68f267 100644 --- a/docs/content/advanced/backend/plugins/overview.md +++ b/docs/content/advanced/backend/plugins/overview.md @@ -14,6 +14,8 @@ An alternative approach is developing a custom way of handling payment on your e Plugins run within the same process as the core Medusa server eliminating the need for extra server capacity, infrastructure, and maintenance. As a result, plugins can use all other services as dependencies and access the database. +--- + ## Using Existing Plugins ### Official Plugins @@ -48,7 +50,9 @@ If you’re installing an official plugin from the Medusa repository, you can fi For community plugins, please refer to the installation instructions of that plugin to learn about any required configurations. -## What’s Next +--- -- Learn how to [create your own plugin](create.md). -- Learn how to [create a fulfillment provider](../shipping/add-fulfillment-provider.md) or a [payment provider](../payment/how-to-create-payment-provider.md). +## See Also + +- [Create your own plugin](create.md) +- [Create a fulfillment provider](../shipping/add-fulfillment-provider.md) or a [payment provider](../payment/how-to-create-payment-provider.md) diff --git a/docs/content/advanced/backend/price-lists/index.md b/docs/content/advanced/backend/price-lists/index.md index 4784a019e9..f8b10cdba4 100644 --- a/docs/content/advanced/backend/price-lists/index.md +++ b/docs/content/advanced/backend/price-lists/index.md @@ -81,7 +81,7 @@ Since the line item belongs to a cart, there’s no need to pass the `region_id` --- -## What’s Next +## See Also -- Learn more about [price selection strategies](../price-selection-strategy/index.md). -- Learn [how to use the PriceList Admin APIs](./use-api.mdx). +- [Price Selection Strategy Overview](../price-selection-strategy/index.md). +- [Use the PriceList Admin APIs](./use-api.mdx). diff --git a/docs/content/advanced/backend/price-lists/use-api.mdx b/docs/content/advanced/backend/price-lists/use-api.mdx index 5aaf77a0a4..3e15111314 100644 --- a/docs/content/advanced/backend/price-lists/use-api.mdx +++ b/docs/content/advanced/backend/price-lists/use-api.mdx @@ -474,7 +474,7 @@ This request returns the ID of the deleted price list. --- -## What’s Next +## See Also -- Learn more about [price lists](./index.md). -- Learn how the [price selection strategy works](../price-selection-strategy/index.md). \ No newline at end of file +- [Price Lists Overview](./index.md). +- [Price Selection Strategy Overview](../price-selection-strategy/index.md). diff --git a/docs/content/advanced/backend/price-selection-strategy/index.md b/docs/content/advanced/backend/price-selection-strategy/index.md index 4d552d81d5..1d4adcc7a7 100644 --- a/docs/content/advanced/backend/price-selection-strategy/index.md +++ b/docs/content/advanced/backend/price-selection-strategy/index.md @@ -60,7 +60,7 @@ The context that is passed to the `calculateVariantPrice` method is an object th --- -## What’s Next +## See Also -- Learn [how to override the price selection strategy](./override.md). -- Learn more about [price lists](./../price-lists/index.md). +- [Override the Price Selection Strategy](./override.md) +- [Price Lists Overview](./../price-lists/index.md) diff --git a/docs/content/advanced/backend/price-selection-strategy/override.md b/docs/content/advanced/backend/price-selection-strategy/override.md index a1274a2785..ad21f5949d 100644 --- a/docs/content/advanced/backend/price-selection-strategy/override.md +++ b/docs/content/advanced/backend/price-selection-strategy/override.md @@ -114,6 +114,6 @@ Then, try out your strategy using any of the [Products](https://docs.medusajs.co --- -## What’s Next +## See Also -- Learn more about [price list selection strategy](./index.md). +- [Price List Selection Strategy Overview](./index.md) diff --git a/docs/content/advanced/backend/regions/overview.md b/docs/content/advanced/backend/regions/overview.md index d374500bbb..5bf329ba4c 100644 --- a/docs/content/advanced/backend/regions/overview.md +++ b/docs/content/advanced/backend/regions/overview.md @@ -111,7 +111,7 @@ The relation between the `Region` and `TaxRate` entities is available on both en --- -## What’s Next +## See Also -- Learn [how to use regions in a storefront using the store REST APIs](../../storefront/use-regions.mdx). -- Learn how to [manage regions using the admin REST APIs](../../admin/manage-regions.mdx). +- [Use Regions in a storefront](../../storefront/use-regions.mdx). +- [Use Regions in the admin](../../admin/manage-regions.mdx). diff --git a/docs/content/advanced/backend/sales-channels/index.md b/docs/content/advanced/backend/sales-channels/index.md index 7d48c47d42..6101eaba79 100644 --- a/docs/content/advanced/backend/sales-channels/index.md +++ b/docs/content/advanced/backend/sales-channels/index.md @@ -68,7 +68,7 @@ The relation is implemented in the [Order](../../../references/entities/classes/ --- -## What’s Next +## See Also -- Learn how to [manage Sales Channels using the Admin APIs](./manage-admin.mdx). -- Check out the [Sales Channel’s Admin APIs](https://docs.medusajs.com/api/admin/#tag/Sales-Channel). +- [Manage Sales Channels using the Admin APIs](./manage-admin.mdx) +- [Sales Channel’s Admin APIs Reference](/api/admin/#tag/Sales-Channel) diff --git a/docs/content/advanced/backend/sales-channels/manage-admin.mdx b/docs/content/advanced/backend/sales-channels/manage-admin.mdx index 0890652a19..a9dfa95e6e 100644 --- a/docs/content/advanced/backend/sales-channels/manage-admin.mdx +++ b/docs/content/advanced/backend/sales-channels/manage-admin.mdx @@ -530,6 +530,6 @@ The request returns an array of orders that are associated with the specified sa --- -## What’s Next +## See Also -- Learn more about [Sales Channels and how they work](./index.md). \ No newline at end of file +- [Sales Channels Overview](./index.md). \ No newline at end of file diff --git a/docs/content/advanced/backend/scheduled-jobs/create.md b/docs/content/advanced/backend/scheduled-jobs/create.md index 6debd1072f..bed15584f0 100644 --- a/docs/content/advanced/backend/scheduled-jobs/create.md +++ b/docs/content/advanced/backend/scheduled-jobs/create.md @@ -8,6 +8,8 @@ Medusa allows you to create scheduled jobs that run at specific times during you This guide explains how to create a scheduled job on your Medusa server. The scheduled job in this example will simply change the status of draft products to `published`. +--- + ## Prerequisites ### Medusa Components @@ -18,6 +20,8 @@ It is assumed that you already have a Medusa server installed and set up. If not Redis is required for scheduled jobs to work. Make sure you [install Redis](../../../tutorial/0-set-up-your-development-environment.mdx#redis) and [configure it with your Medusa server](../../../usage/configurations.md#redis). +--- + ## 1. Create a File Each scheduled job should reside in a TypeScript or JavaScript file under the `src/loaders` directory. @@ -26,6 +30,8 @@ Start by creating the `src/loaders` directory. Then, inside that directory, crea For the example in this tutorial, you can create the file `src/loaders/publish.ts`. +--- + ## 2. Create Cron Job To create a scheduled job, add the following code in the file you created, which is `src/loaders/publish.ts` in this example: @@ -89,6 +95,8 @@ jobSchedulerService.create("publish-products", { }); ``` +--- + ## 3. Run Medusa Server :::info @@ -129,6 +137,8 @@ To test the previous example out instantly, you can change the scheduled job exp ::: -## What’s Next +--- -- Learn more about [services and how you can use them](../services/overview.md). +## See Also + +- [Services Overview](../services/overview.md). diff --git a/docs/content/advanced/backend/services/create-service.md b/docs/content/advanced/backend/services/create-service.md index 3b521eed30..03a7d73470 100644 --- a/docs/content/advanced/backend/services/create-service.md +++ b/docs/content/advanced/backend/services/create-service.md @@ -23,6 +23,8 @@ class HelloService extends TransactionBaseService { export default HelloService ``` +--- + ## Service Constructor As the service extends the `TransactionBaseService` class, all services in Medusa’s core, as well as all your custom services, will be available in your service’s constructor using dependency injection. @@ -46,6 +48,8 @@ async getProductCount() { } ``` +--- + ## Use a Service In this section, you'll learn how to use services throughout your Medusa server. This includes both Medusa's services and your custom services. @@ -93,7 +97,9 @@ constructor({ helloService, eventBusService }) { } ``` -## What’s Next +--- -- Check out the [Services Reference](/references/services/classes/AuthService) to see a list of all services in Medusa. -- [Learn How to Create an Endpoint.](../endpoints/add.md) +## See Also + +- [Services Reference](/references/services/classes/AuthService) +- [Create an Endpoint](../endpoints/add.md) diff --git a/docs/content/advanced/backend/services/overview.md b/docs/content/advanced/backend/services/overview.md index 4fe54a9f25..6d4209f895 100644 --- a/docs/content/advanced/backend/services/overview.md +++ b/docs/content/advanced/backend/services/overview.md @@ -18,7 +18,9 @@ For example, if the file name is `hello.ts`, the service will be registered as ` The registration name of the service is important, as you’ll be referring to it when you want to get access to the service using dependency injection or in routes. -## What's Next +--- -- Learn [how to create a service](./create-service.md) -- Check out the [Services Reference](/references/services/classes/AuthService) to see a list of all services in Medusa. +## See Also + +- [Create a Service](./create-service.md) +- [Services Reference](/references/services/classes/AuthService) diff --git a/docs/content/advanced/backend/shipping/add-fulfillment-provider.md b/docs/content/advanced/backend/shipping/add-fulfillment-provider.md index 7bc75b204a..fadd7b0a24 100644 --- a/docs/content/advanced/backend/shipping/add-fulfillment-provider.md +++ b/docs/content/advanced/backend/shipping/add-fulfillment-provider.md @@ -19,6 +19,8 @@ Also, the fulfillment provider class should have a static property `identifier`. Fulfillment providers are loaded and installed on the server startup. +--- + ## Create a Fulfillment Provider The first step is to create a JavaScript or TypeScript file under `src/services`. For example, create the file `src/services/my-fulfillment.ts` with the following content: @@ -269,7 +271,8 @@ cancelFulfillment(fulfillment) { } ``` -## What’s Next +--- -- Check out the [Webshipper plugin](https://github.com/medusajs/medusa/tree/cab5821f55cfa448c575a20250c918b7fc6835c9/packages/medusa-fulfillment-webshipper) for an example of a fulfillment provider that interacts with a third-party providers. -- Check out the [manual fulfillment plugin](https://github.com/medusajs/medusa/tree/cab5821f55cfa448c575a20250c918b7fc6835c9/packages/medusa-fulfillment-manual) for a basic implementation of a fulfillment provider. +## See Also + +- Example Implementations: [Webshipper plugin](https://github.com/medusajs/medusa/tree/cab5821f55cfa448c575a20250c918b7fc6835c9/packages/medusa-fulfillment-webshipper) and the [manual fulfillment plugin](https://github.com/medusajs/medusa/tree/cab5821f55cfa448c575a20250c918b7fc6835c9/packages/medusa-fulfillment-manual) diff --git a/docs/content/advanced/backend/shipping/overview.md b/docs/content/advanced/backend/shipping/overview.md index c95fd0055d..e5c9f1384e 100644 --- a/docs/content/advanced/backend/shipping/overview.md +++ b/docs/content/advanced/backend/shipping/overview.md @@ -10,6 +10,8 @@ The distinction between the four is important. It has been carefully planned and It’s also constructed to support multiple regions, provide different shipment configurations and options for different product types, provide promotional shipments for your customers, and much more. +--- + ## Summary - **Fulfillment Provider:** Fulfillment providers are plugins or [Services](../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. @@ -19,6 +21,8 @@ It’s also constructed to support multiple regions, provide different shipment ![Shipping Architecture](https://res.cloudinary.com/dza7lstvk/image/upload/v1668001762/Medusa%20Docs/Diagrams/QII2Hvn_vjkrdy.png) +--- + ## Fulfillment Provider A Fulfillment Provider in Medusa is a method to handle shipping products in selected regions. It is not associated with a cart, customer, or order in particular. @@ -43,6 +47,8 @@ Once the Fulfillment Provider is added to the server, the store operator will be The [`FulfillmentProvider`](../../../references/entities/classes/FulfillmentProvider.md) entity only has 2 attributes: `is_installed` to indicate if the fulfillment provider is installed and its value is a boolean; and `id` which is the unique identifier that you define in the Fulfillment Provider Service. +--- + ## Shipping Profile Shipping profiles are the highest in the hierarchy in the shipping architecture. @@ -69,6 +75,8 @@ The `ShippingProfile` has a `type` attribute that can be `default`, `gift_ca The `ShippingProfile` entity also has an array of `ShippingOption` instances. +--- + ## Shipping Option After the admin adds a shipping profile, they can add shipping options that belong to that shipping profile from the admin dashboard. @@ -105,6 +113,8 @@ The `data` attribute is used to specify any data necessary for fulfilling the The `data` attribute does not have any specific format. It’s up to you to choose whatever data is included here. +--- + ## Shipping Method Unlike the previous two components, a shipping method is not created by the admin. It’s created when a `POST` request is sent to `/store/carts/:id/shipping-methods` after the customer chooses a shipping option. @@ -135,7 +145,9 @@ The `ShippingMethod` also belongs to the `Order` entity. This association is The `ShippingMethod` instance holds a `price` attribute, which will either be the flat rate price or the calculated price. -## What’s Next +--- -- [Learn how to Create a Fulfillment Provider.](./add-fulfillment-provider.md) -- Check out [available shipping plugins](https://github.com/medusajs/medusa/tree/master/packages). +## See Also + +- [Create a Fulfillment Provider](./add-fulfillment-provider.md) +- [Available shipping plugins](https://github.com/medusajs/medusa/tree/master/packages) diff --git a/docs/content/advanced/backend/subscribers/create-subscriber.md b/docs/content/advanced/backend/subscribers/create-subscriber.md index 7a63a2151d..da6172b7bb 100644 --- a/docs/content/advanced/backend/subscribers/create-subscriber.md +++ b/docs/content/advanced/backend/subscribers/create-subscriber.md @@ -8,6 +8,8 @@ Medusa's event system works by pushing data to a Queue that each handler then ge You can learn how to [install Redis](../../../tutorial/0-set-up-your-development-environment.mdx#redis) and [configure it with Medusa](../../../usage/configurations.md#redis) before you get started. +--- + ## Implementation A subscriber is a TypeScript or JavaScript file that is created under `src/subscribers`. Its file name, by convension, should be the class name of the subscriber without the word `Subscriber`. For example, if the subscriber is `HelloSubscriber`, the file name should be `hello.ts`. @@ -40,6 +42,8 @@ The `data` object won't contain other order data. Only the ID of the order. You ::: +--- + ## Using Services in Subscribers You can access any service through the dependencies injected to your subscriber’s constructor. @@ -69,7 +73,9 @@ When using attributes defined in the subscriber, such as the `productService` in ::: -## What’s Next +--- -- [View the list of all events](events-list.md) -- [Learn how to create a service.](/advanced/backend/services/create-service) +## See Also + +- [Events reference](events-list.md) +- [Create a Service](../services/create-service) diff --git a/docs/content/advanced/backend/subscribers/events-list.md b/docs/content/advanced/backend/subscribers/events-list.md index 02953731bc..68b8e26e27 100644 --- a/docs/content/advanced/backend/subscribers/events-list.md +++ b/docs/content/advanced/backend/subscribers/events-list.md @@ -6,6 +6,8 @@ This document details all events in Medusa, when they are triggered, and what da It is assumed you’re already familiar with [Subscribers in Medusa and how to listen to events](create-subscriber.md). You can then use the name of events from this documentation in your subscriber to listen to events. +--- + ## Legend Events in this document are listed under the entity they’re associated with. They’re listed in a table of three columns: @@ -14,6 +16,8 @@ Events in this document are listed under the entity they’re associated with. T 2. **Description:** When this event is triggered. 3. **Event Data Payload**: The data your handler receives as a parameter. +--- + ## Batch Jobs Events This section holds all events related to batch jobs. @@ -208,6 +212,8 @@ Object of the following format: +--- + ## Cart Events This section holds all events related to a cart. @@ -284,6 +290,8 @@ An object with at least the ID of the cart, however, in most cases the entire ca +--- + ## Claim Events This section holds all events related to claims. @@ -459,6 +467,8 @@ Object of the following format: +--- + ## Claim Item Events This section holds all events related to claim items. @@ -553,6 +563,8 @@ Object of the following format: +--- + ## Currency Events This section holds all events related to currencies. @@ -599,6 +611,8 @@ Object of the following format: +--- + ## Customer Events This section holds all events related to customers. @@ -685,6 +699,8 @@ Object of the following format: +--- + ## Draft Order Events This section holds all events related to draft orders. @@ -755,6 +771,8 @@ Object of the following format: +--- + ## Gift Card Events This section holds all events related to gift cards. @@ -802,6 +820,8 @@ Object of the following format: +--- + ## Invite Events This section holds all events related to invites. @@ -849,6 +869,8 @@ Object of the following format: +--- + ## Note Events This section holds all events related to notes. @@ -943,6 +965,8 @@ Object of the following format: +--- + ## App Authentication Events This section holds all events related to app authentications. @@ -1008,6 +1032,8 @@ The returned data from the method `refreshToken` in the auth handler service of +--- + ## Order Events This section holds all events related to orders. @@ -1460,6 +1486,8 @@ Object of the following format: +--- + ## Order Edit Events This section holds all events related to order edits. @@ -1637,6 +1665,8 @@ Object of the following format: +--- + ## Order Edit Item Changes Events This section holds all events related to order edit item changes. @@ -1714,6 +1744,8 @@ Triggered when an order edit item change is deleted. +--- + ## Payment Events This section holds all events related to payment. @@ -1859,6 +1891,8 @@ The entire payment passed as an object. You can refer to the [Payment entity](.. +--- + ## Payment Collection Events This section holds all events related to payment collections. @@ -1954,6 +1988,8 @@ The entire payment collection passed as an object. You can refer to the [Payment +--- + ## Product Events This section holds all events related to products. @@ -2052,6 +2088,8 @@ Object of the following format: +--- + ## Product Variant Events This section holds all events related to product variants. @@ -2151,6 +2189,8 @@ Object of the following format: +--- + ## Publishable API Key Events This section holds all events related to publishable API keys. @@ -2233,6 +2273,8 @@ Object of the following format: +--- + ## Region Events This section holds all events related to regions. @@ -2327,6 +2369,8 @@ Object of the following format: +--- + ## Sales Channel Events This section holds all events related to sales channels. @@ -2431,6 +2475,8 @@ Object of the following format: +--- + ## Swap Events This section holds all events related to swaps. @@ -2681,6 +2727,8 @@ Object of the following format: +--- + ## Token Events This section holds all events related to tokens. @@ -2730,6 +2778,8 @@ Object of the following format: +--- + ## User Events This section holds all events related to users. @@ -2848,7 +2898,9 @@ Object of the following format: -## What’s Next +--- -- Learn how you can [use services in subscribers](create-subscriber.md#using-services-in-subscribers). -- Learn how to [create notifications](../notification/overview.md) in Medusa. +## See Also + +- [Use services in subscribers](create-subscriber.md#using-services-in-subscribers) +- [Create a notification provider](../notification/overview.md) diff --git a/docs/content/advanced/backend/subscribers/overview.md b/docs/content/advanced/backend/subscribers/overview.md index 2fd87d677f..ea8f46aa6d 100644 --- a/docs/content/advanced/backend/subscribers/overview.md +++ b/docs/content/advanced/backend/subscribers/overview.md @@ -10,6 +10,8 @@ The purpose of these events is to allow other parts of the platform, or third-pa Medusa's queuing and events system is handled by Redis. So, you must have [Redis configured](../../../tutorial/0-set-up-your-development-environment.mdx#redis) on your server to use subscribers. +--- + ## What are Subscribers Subscribers register handlers for an events and allows you to perform an action when that event occurs. For example, if you want to send your customer an email when they place an order, then you can listen to the `order.placed` event and send the email when the event is emitted. @@ -20,7 +22,9 @@ Custom subscribers are TypeScript or JavaScript files in your project's `src/sub Whenever an event is emitted, the subscriber’s registered handler method is executed. The handler method receives as a parameter an object that holds data related to the event. For example, if an order is placed the `order.placed` event will be emitted and all the handlers will receive the order id in the parameter object. -## What's Next +--- -- Learn [how to create a Subscriber](create-subscriber.md). -- [View the list of all events](events-list.md). +## See Also + +- [Create a Subscriber](create-subscriber.md). +- [Events reference](events-list.md). diff --git a/docs/content/advanced/backend/taxes/inclusive-pricing.md b/docs/content/advanced/backend/taxes/inclusive-pricing.md index 73e55952cd..ca2c036c65 100644 --- a/docs/content/advanced/backend/taxes/inclusive-pricing.md +++ b/docs/content/advanced/backend/taxes/inclusive-pricing.md @@ -21,6 +21,8 @@ This can be useful when some countries have the same currency but have different Then, Medusa handles calculating the tax amount using the tax rate and the tax-inclusive price. This is managed in the backend and relayed to accounting and analytics tools. +--- + ## How is Tax Inclusivity Defined Tax inclusivity can be toggled for regions, currencies, price lists, and shipping options either during creation or while editing. This is represented by the boolean attribute `includes_tax` available in the entities `Region`, `Currency`, `PriceList`, and `ShippingOption`. By default, this attribute is set to `false`. @@ -54,6 +56,8 @@ When a shipping option is selected, a shipping method is created based on that s The `ShippingMethod` entity also has the `includes_tax` attribute. Its value is the same as the value of `includes_tax` of the shipping option the method is associated with. +--- + ## Tax Amount Calculation Formula When a price is tax-inclusive, the tax amount is calculated using the following formula: @@ -66,6 +70,8 @@ Where `taxRate` is the tax rate to be applied to the price, and `taxInclusivePri For example, if the tax rate is `0.25` and the price of a product is `100`, the resulting tax amount calculated by Medusa will be `0.25 * 100 / 1.25 = 20`. +--- + ## Retrieving Tax Amounts This section covers at which point tax amounts are calculated for different entities, how they are calculated when the price is tax inclusive, and what fields can be returned in the endpoints relative to each of the entities. @@ -187,7 +193,9 @@ The relevant fields are: During the calculation of the totals of different components of the cart or order, such as shipping or line items, if tax inclusivity is enabled on that component, a process similar to those explained above will be applied to retrieve the total. -## What’s Next +--- -- Learn how to [calculate taxes manually](manual-calculation.md). -- [Check out the API reference](https://docs.medusajs.com/api/store/). +## See Also + +- [Calculate taxes manually](manual-calculation.md) +- [Storefront API reference](/api/store) diff --git a/docs/content/advanced/backend/taxes/manual-calculation.md b/docs/content/advanced/backend/taxes/manual-calculation.md index c3bbedeb85..63a6302d88 100644 --- a/docs/content/advanced/backend/taxes/manual-calculation.md +++ b/docs/content/advanced/backend/taxes/manual-calculation.md @@ -8,6 +8,8 @@ By default, taxes are automatically calculated by Medusa during checkout. This b If you disable this behavior, you must manually trigger taxes calculation. When taxes are calculated, this means that requests will be sent to the tax provider to retrieve the tax rates. +--- + ## How to Manually Calculate Taxes in Checkout This section explores different ways you can calculate taxes based on your purpose. @@ -80,7 +82,9 @@ You can learn how to [retrieve and use services](../services/create-service.md#u ::: -## What’s Next +--- -- Learn about [tax-inclusive pricing](inclusive-pricing.md). -- Learn about available methods in [CartsService](../../../references/services/classes/CartService.md) and [TotalsService](../../../references/services/classes/TotalsService.md). +## See Also + +- [Tax-Inclusive Pricing Overview](inclusive-pricing.md) +- [CartsService](../../../references/services/classes/CartService.md) and [TotalsService](../../../references/services/classes/TotalsService.md) diff --git a/docs/content/advanced/backend/upgrade-guides/1-3-0.md b/docs/content/advanced/backend/upgrade-guides/1-3-0.md index a4710f6264..14001b73c9 100644 --- a/docs/content/advanced/backend/upgrade-guides/1-3-0.md +++ b/docs/content/advanced/backend/upgrade-guides/1-3-0.md @@ -20,6 +20,8 @@ TYPEORM_MIGRATIONS=./node_modules/@medusajs/medusa/dist/migrations/*.js These environment variables are used in the data migration scripts in this upgrade. Make sure to replace `` with your PostgreSQL database URL. +--- + ## Environment Variables In previous versions of Medusa, The server automatically loads all environment variables in the `.env` file at the root of the Medusa server. @@ -58,6 +60,8 @@ const dotenv = require('dotenv') } ``` +--- + ## Line Item Adjustments This new version of Medusa allows store operators to adjust line items in an order or a swap which provides more customization capabilities. @@ -76,6 +80,8 @@ For that reason, it’s essential to run the data migration script after upgradi node ./node_modules/@medusajs/medusa/dist/scripts/line-item-adjustment-migration.js ``` +--- + ## Advanced Discount Conditions This new version of Medusa holds advanced promotions functionalities to provide store operators with even more customization capabilities when creating discounts. You can now add even more conditions to your discounts to make them specific for a set of products, collections, customer groups, and more. diff --git a/docs/content/advanced/backend/upgrade-guides/1-3-6.md b/docs/content/advanced/backend/upgrade-guides/1-3-6.md index c0a2bd0def..7f021aef8a 100644 --- a/docs/content/advanced/backend/upgrade-guides/1-3-6.md +++ b/docs/content/advanced/backend/upgrade-guides/1-3-6.md @@ -26,6 +26,8 @@ TYPEORM_MIGRATIONS=./node_modules/@medusajs/medusa/dist/migrations/*.js These environment variables are used in the data migration scripts in this upgrade. Make sure to replace `` with your PostgreSQL database URL. +--- + ## Sales Channels Sales Channels were introduced in v1.3.5 guarded by a [feature flag](../feature-flags/toggle.md). By enabling Sales Channels, developers and users can associate products and other entities with a specific Sales Channel. diff --git a/docs/content/advanced/backend/upgrade-guides/1-3-8.md b/docs/content/advanced/backend/upgrade-guides/1-3-8.md index 95a151edfe..15fd523957 100644 --- a/docs/content/advanced/backend/upgrade-guides/1-3-8.md +++ b/docs/content/advanced/backend/upgrade-guides/1-3-8.md @@ -10,6 +10,8 @@ Updating your medusa server to version `1.3.8` may cause issues when using NPM. It's highly recommended to use [yarn](https://yarnpkg.com/) when working with Medusa. Updating with yarn should resolve any issues you might run into during the update. +--- + ## Resolving Update Issues with NPM ### Update All Medusa Dependencies diff --git a/docs/content/advanced/backend/upgrade-guides/1-6-1.md b/docs/content/advanced/backend/upgrade-guides/1-6-1.md index 77b23ece1c..8c6d2a7365 100644 --- a/docs/content/advanced/backend/upgrade-guides/1-6-1.md +++ b/docs/content/advanced/backend/upgrade-guides/1-6-1.md @@ -12,6 +12,8 @@ As the new version `1.6.1` make changes to the database schema, it is required t Without running the migrations, you might have trouble accessing and using the Medusa admin. +--- + ## Actions Required After updating your server, run migrations with the following command: diff --git a/docs/content/advanced/backend/upgrade-guides/1-7-0.md b/docs/content/advanced/backend/upgrade-guides/1-7-0.md index a5eebd7e95..a13bed0c79 100644 --- a/docs/content/advanced/backend/upgrade-guides/1-7-0.md +++ b/docs/content/advanced/backend/upgrade-guides/1-7-0.md @@ -12,6 +12,8 @@ In this new version, the method [`retrieveByEmail` in the Customer Service](../. In addition, after introducing the Claim Order feature, this version of Medusa introduces changes in the database that allows two customers having the same email based on the value of the `has_account` field. This change requires running migrations after the update. +--- + ## Actions Required ### Run Migrations diff --git a/docs/content/advanced/backend/upgrade-guides/1-7-1.md b/docs/content/advanced/backend/upgrade-guides/1-7-1.md index 86588ab717..fe370bb730 100644 --- a/docs/content/advanced/backend/upgrade-guides/1-7-1.md +++ b/docs/content/advanced/backend/upgrade-guides/1-7-1.md @@ -14,6 +14,8 @@ With this introduction, the previous use of `EventBus` to create a cron job has In addition, this version features some fixes to gift cards that requires running migrations, and changes to how payment providers are implemented. +--- + ## Actions Required ### Run Migrations diff --git a/docs/content/advanced/backend/upgrade-guides/admin/admin-vite.md b/docs/content/advanced/backend/upgrade-guides/admin/admin-vite.md index ffe9ddc266..07b20e27f0 100644 --- a/docs/content/advanced/backend/upgrade-guides/admin/admin-vite.md +++ b/docs/content/advanced/backend/upgrade-guides/admin/admin-vite.md @@ -12,6 +12,8 @@ Medusa Admin previously was built using Gatsby. As of a recent update, the Admin This introduced breaking changes related to environment variables used and the published directory. Read below for actions required following this update. +--- + ## Required Node.js Version @@ -20,6 +22,8 @@ Following the change to Vite 3, the required Node.js version for the Admin has c +--- + ## Changed Environment Variables Previously, the Medusa Admin used the environment variables `GATSBY_MEDUSA_BACKEND_URL` or `GATSBY_STORE_URL` to store the Medusa server’s URL. @@ -36,6 +40,8 @@ Change your `GATSBY_MEDUSA_BACKEND_URL` or `GATSBY_STORE_URL` environment variab MEDUSA_BACKEND_URL= ``` +--- + ## Changed Publish Directory Previously, the build output of the Medusa Admin was placed in the `dist` directory. After this update, the build output is placed in the `public` directory. diff --git a/docs/content/advanced/ecommerce/handle-order-claim-event.md b/docs/content/advanced/ecommerce/handle-order-claim-event.md index 3bd0464855..09661d7de0 100644 --- a/docs/content/advanced/ecommerce/handle-order-claim-event.md +++ b/docs/content/advanced/ecommerce/handle-order-claim-event.md @@ -14,6 +14,8 @@ When the customer requests to claim the order, the event `order-update-token.cre In this document, you’ll learn how to handle the `order-update-token.created` event on the server to send the customer a confirmation email. +--- + ## Prerequisites ### Medusa Components @@ -30,6 +32,8 @@ To send an email or another type of notification method, you must have a notific This document has an example using the [SendGrid](../../add-plugins/sendgrid.mdx) plugin. +--- + ## Step 1: Create a Subscriber To subscribe to and handle an event, you must create a subscriber. @@ -66,6 +70,8 @@ You can learn more about dependency injection in [this documentation](../backend ::: +--- + ## Step 2: Subscribe to the Event In the subscriber you created, add the following in the `constructor`: @@ -105,6 +111,8 @@ In this method, you should typically send an email to the customer’s old email The page would then send a request to the server to verify that the `token` is valid and associate the order with the customer. You can read more about how to implement this in your storefront in [this documentation](../storefront/implement-claim-order.mdx). +--- + ## Example: Using SendGrid For example, you can implement this subscriber to send emails using SendGrid: @@ -144,6 +152,8 @@ export default ClaimOrderSubscriber; Notice how the `token` is passed to the storefront link as a parameter. +--- + ## See Also -- Learn [how to implement claim-order flow in your storefront](../storefront/implement-claim-order.mdx). \ No newline at end of file +- [Implement claim-order flow in your storefront](../storefront/implement-claim-order.mdx) diff --git a/docs/content/advanced/storefront/handle-order-edits.mdx b/docs/content/advanced/storefront/handle-order-edits.mdx index b73aca124d..23adf75435 100644 --- a/docs/content/advanced/storefront/handle-order-edits.mdx +++ b/docs/content/advanced/storefront/handle-order-edits.mdx @@ -16,6 +16,8 @@ You can learn more about enabling it in the [feature flags](../backend/feature-f ::: +--- + ## Overview A merchant can request to edit an order to make changes to its items. The change can include removing an item, adding a new item, and changing the quantity of an item in the original order. @@ -44,6 +46,8 @@ You can perform other functionalities related to order editing. To learn more, c ::: +--- + ## Prerequisites ### Medusa Components @@ -62,6 +66,8 @@ If you follow the JS Client code blocks, it’s assumed you already have [Medusa You must have an existing order edit in the “request” state. +--- + ## Retrieve an Order Edit You can retrieve a single order edit by its ID by sending a request to the [Get Order Edit](/api/store/#tag/OrderEdit/operation/GetOrderEditsOrderEdit) endpoint: @@ -142,6 +148,8 @@ Here’s an example of how you can use this data to show the customer the reques ``` +--- + ## Handle Payment After viewing the changes in the order edit, the customer can choose to confirm or decline the order edit. @@ -232,6 +240,8 @@ fetch(`/store/payment-collection/${paymentCollectionId}/sessions/${p After performing the above steps, you can [complete the Order Edit](#complete-the-order-edit). +--- + ## Complete the Order Edit To confirm and complete the order edit, send a request to the [Complete Order Edit](/api/store/#tag/OrderEdit/operation/PostOrderEditsOrderEditComplete) endpoint: @@ -275,6 +285,8 @@ If the payment isn’t authorized first, the order edit completion will fail. ::: +--- + ## Decline an Order Edit If the customer wants to decline the Order Edit, you can do that by sending a request to the Decline Order Edit endpoint: @@ -320,7 +332,9 @@ In the request body parameters, you can optionally pass the `decline_reason` par If the Order Edit is declined, the changes requested in the Order Edit aren't reflected on the original order and no refund or additional payments are required. -## What’s Next +--- -- Learn [how to edit an order using Admin APIs](../admin/order-edit.mdx) -- Learn more about [order edit endpoints in the API reference](/api/store/#tag/OrderEdit) +## See Also + +- [Order Edit API reference](/api/store/#tag/OrderEdit) +- [Edit an order using Admin APIs](../admin/order-edit.mdx) diff --git a/docs/content/advanced/storefront/how-to-implement-checkout-flow.mdx b/docs/content/advanced/storefront/how-to-implement-checkout-flow.mdx index 7a48e1d838..927234691b 100644 --- a/docs/content/advanced/storefront/how-to-implement-checkout-flow.mdx +++ b/docs/content/advanced/storefront/how-to-implement-checkout-flow.mdx @@ -17,6 +17,8 @@ It’s recommended to go through the [Shipping Architecture Overview](../backend ::: +--- + ## Prerequisites ### Medusa Components @@ -37,6 +39,8 @@ This document assumes you’ve already taken care of the add-to-cart flow. So, y You can learn how to implement the cart flow using [this documentation](../../guides/carts-in-medusa.mdx). +--- + ## Shipping Step In this step, the customer generally enters their shipping info, then chooses the available shipping option based on the entered info. @@ -106,6 +110,8 @@ This request accepts the ID of the cart as a path parameter and the new shipping The request returns the updated cart, with the new shipping address available in `cart.shipping_address`. +--- + ### List Shipping Options After updating the cart with the customer’s address, the list of available [shipping options](../backend/shipping/overview.md#shipping-option) for that cart might change. So, you should retrieve the updated list of options. @@ -183,6 +189,8 @@ The request accepts the ID of the cart as a path parameter and its body the ID o It returns the updated cart, with the created shipping method available in the array `cart.shipping_methods`. +--- + ## Payment Step In this step, the customer generally chooses a payment method to complete their purchase. The implementation of payment providers is done differently for each provider, so this section will just show the general steps you should follow when implementing this step. @@ -366,8 +374,11 @@ The request returns two properties: `type` and `data`. If the order was placed s If an error occurred while placing the order, `type` will be `cart` and `data` will be the cart's data. -## What’s Next +--- -- Learn more about the [JS Client and how to use it](../../js-client/overview.md). +## See Also + +- [Medusa JS Client Overview](../../js-client/overview.md). - Check out available plugins for popular payment providers such as [Stripe](../../add-plugins/stripe.md) and [PayPal](/add-plugins/paypal.md). -- Learn more about the [Payment](../backend/payment/overview.md) and [Shipping](../backend/shipping/overview.md) Architectures. +- [Payment Architecture](../backend/payment/overview.md) +- [Shipping Architecture](../backend/shipping/overview.md) diff --git a/docs/content/advanced/storefront/implement-claim-order.mdx b/docs/content/advanced/storefront/implement-claim-order.mdx index f3cac997f6..77129496d6 100644 --- a/docs/content/advanced/storefront/implement-claim-order.mdx +++ b/docs/content/advanced/storefront/implement-claim-order.mdx @@ -32,6 +32,8 @@ In this document, you’ll learn how to implement two parts of this flow: 1. Allow customers to claim their orders. 2. Verify a claim to an order. +--- + ## Prerequisites ### Medusa Components @@ -58,6 +60,8 @@ It is assumed you already have an order placed by a guest customer. You can refe In addition, it is assumed you already have a logged-in customer before performing the steps in this document. You can refer to the [API reference](/api/store/#tag/Auth/operation/PostAuth) for more details on that. +--- + ## Request to Claim an Order When the customer wants to claim an order, they must supply its ID. @@ -114,6 +118,8 @@ If the customer’s request has been processed successfully, the request returns The customer at this point will receive an email with a link to verify their claim on the order. +--- + ## Manually Verify a Claim to an Order The link in the email that the customer receives should be a page in your storefront that accepts a `token` query parameter. @@ -164,6 +170,8 @@ This request accepts as a body parameter the string `token`. This would be the t If the verification is successful, the order will now be associated with the customer and the customer will be able to see it among their orders. +--- + ## See Also -- Learn [how to send a confirmation email to claim an order](../ecommerce/handle-order-claim-event.md). +- [Send a confirmation email to claim an order](../ecommerce/handle-order-claim-event.md) diff --git a/docs/content/advanced/storefront/use-discounts-in-checkout.mdx b/docs/content/advanced/storefront/use-discounts-in-checkout.mdx index 20dd87cea0..cb8905c5ba 100644 --- a/docs/content/advanced/storefront/use-discounts-in-checkout.mdx +++ b/docs/content/advanced/storefront/use-discounts-in-checkout.mdx @@ -17,10 +17,12 @@ Customers can use discounts during checkout to benefit from promotions that the In this document, you’ll learn how to add a discount to a cart, how to display details related to the discount, and how to remove a discount from a cart. -## Scenario +### Scenario You want to implement discount functionality in your store to allow customers to apply discount codes to their cart and remove them from the cart. You also want to display the discount details for the customer. +--- + ## Prerequisites ### Medusa Components @@ -41,6 +43,8 @@ This document assumes you’ve already taken care of the add-to-cart flow. So, y You can learn how to implement the cart flow using [this documentation](../../guides/carts-in-medusa.mdx). +--- + ## Add Discount to Cart The customer can enter a discount code during the checkout flow to benefit from a promotion. @@ -110,6 +114,8 @@ If the discount is applied successfully, the entire cart object will be returned In case the customer enters an invalid discount or the discount cannot be applied to the cart because it doesn’t meet its conditions, the request will return an error. You can handle the error in the `catch` method. +--- + ## Display Discount Details After the customer enters a discount code and it is applied to the cart, you can display the discount details to the customer. This shows the customer how much they benefitted from the discount. @@ -201,6 +207,8 @@ The returned `cart` object has the following properties that can be used to disp - The `shipping_total` property is the total shipping amount. If a Free Shipping discount is applied to the cart, `shipping_total` and `discount_total` will be 0. - The `total` property is the total amount of the cart after applying the discount. +--- + ## Remove Discount from Cart The customer can choose to remove a discount from their cart. @@ -238,7 +246,9 @@ This request accepts the cart ID and the code of the discount to remove. If the The totals of the cart and its items will be updated as well. -## What’s Next +--- -- Learn [how to implement the checkout flow](./how-to-implement-checkout-flow.mdx). -- Learn [how to create discounts using the admin APIs](/api/admin/#tag/Discount/operation/PostDiscounts). \ No newline at end of file +## See Also + +- [Implement the checkout flow in a storefront](./how-to-implement-checkout-flow.mdx). +- [Manage discounts using the admin APIs](../admin/manage-discounts.mdx). diff --git a/docs/content/advanced/storefront/use-regions.mdx b/docs/content/advanced/storefront/use-regions.mdx index f564488ab3..9b5d9a7f7e 100644 --- a/docs/content/advanced/storefront/use-regions.mdx +++ b/docs/content/advanced/storefront/use-regions.mdx @@ -169,7 +169,7 @@ This request returns the full object of the updated cart. --- -## What’s Next +## See Also -- Learn [how to implement cart functionalities in your storefront](../../guides/carts-in-medusa.mdx) -- Learn [how to implement checkout in your storefront](./how-to-implement-checkout-flow.mdx) \ No newline at end of file +- [Implement cart functionalities in your storefront](../../guides/carts-in-medusa.mdx) +- [Implement checkout in your storefront](./how-to-implement-checkout-flow.mdx) diff --git a/docs/content/advanced/storefront/use-sales-channels.mdx b/docs/content/advanced/storefront/use-sales-channels.mdx index 33254b6de6..97735f3d25 100644 --- a/docs/content/advanced/storefront/use-sales-channels.mdx +++ b/docs/content/advanced/storefront/use-sales-channels.mdx @@ -11,6 +11,8 @@ In your storefront, you can filter products by sales channels. You can also asso This guide explains how to perform these operations using the Storefront APIs. +--- + ## Prerequisites ### Medusa Components @@ -25,6 +27,8 @@ This guide includes code snippets to send requests to your Medusa server using M If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client installed](../../js-client/overview.md) and have [created an instance of the client](../../js-client/overview.md#configuration). +--- + ## Filter Products by Sales Channel To filter products by a specific sales channel, pass the `sales_channel_id` query parameter to the List Products endpoint: @@ -61,6 +65,8 @@ The `sales_channel_id` query parameter is an array of sales channel IDs. You can The request returns an array of products. These are the products that are available in the sales channel. +--- + ## Associate a Cart with a Sales Channel ### When Creating a Cart @@ -142,7 +148,9 @@ fetch(`/store/carts/${cartId}`, { The request returns the updated cart. -## What’s Next 🚀 +--- -- Learn how to [Implement the Cart functionality in a storefront](../../guides/carts-in-medusa.mdx). -- Learn how to [Implement the Checkout functionality in a storefront](./how-to-implement-checkout-flow.mdx). \ No newline at end of file +## See Also + +- [Implement the Cart functionality in a storefront](../../guides/carts-in-medusa.mdx) +- [Implement the Checkout functionality in a storefront](./how-to-implement-checkout-flow.mdx) diff --git a/docs/content/cli/reference.md b/docs/content/cli/reference.md index 24adca335c..be638b79e3 100644 --- a/docs/content/cli/reference.md +++ b/docs/content/cli/reference.md @@ -8,6 +8,8 @@ The Medusa CLI serves as a tool that allows you to perform important commands wh To use Medusa, it is required to install the CLI tool as it is used to create a new Medusa server. +--- + ## How to Install CLI Tool To install the CLI tool, run the following command in your terminal: @@ -28,6 +30,8 @@ The CLI tool is then available under the `medusa` command. You can see all comma medusa --help ``` +--- + ## Common Options The following options can be used with all available commands. @@ -84,6 +88,8 @@ If used inside a Medusa project, the version of the Medusa CLI and Medusa projec medusa --version ``` +--- + ## Available Commands ### new @@ -206,7 +212,9 @@ medusa telemetry | `--enable` | Enable telemetry (default) | | `--disable` | Disable telemetry | -## What’s Next +--- -- Learn more about [anonymous usage data collection](../usage.md). -- Learn how to [configure your Medusa server](../usage/configurations.md). +## See Also + +- [Configure your Medusa server](../usage/configurations.md) +- [Set up your development environment](../tutorial/0-set-up-your-development-environment.mdx) diff --git a/docs/content/contribution-guidelines.md b/docs/content/contribution-guidelines.md index 644a48550c..9216a7f7a8 100644 --- a/docs/content/contribution-guidelines.md +++ b/docs/content/contribution-guidelines.md @@ -14,27 +14,37 @@ The documentation website is built with [Docusaurus](https://docusaurus.io/), a The documentation codebase is hosted as part of the [medusa repository](https://github.com/medusajs/medusa) on GitHub. You’ll find the code that runs the docusaurus website under the [www/docs](https://github.com/medusajs/medusa/tree/master/www/docs) directory. +--- + ## Documentation Content The documentation content is written in Markdown format and is located in the [docs/content](https://github.com/medusajs/medusa/tree/master/docs/content) directory of the same repository. If you’re not familiar with Markdown, check out [this cheat sheet](https://www.markdownguide.org/cheat-sheet/) for a quick start. You’ll also find MDX files. MDX files combine the power of Markdown with React. So, the content of the file can contain JSX components and import statements, among other features. You can learn more about [MDX in docusaurus’s guide.](https://docusaurus.io/docs/markdown-features/react) +--- + ## What You Can Contribute To - You can contribute to the Docusaurus codebase to add a new feature or fix a bug in the documentation website. - You can contribute to the documentation content either by fixing errors you find or by adding documentation pages. +--- + ## What You Can’t Contribute To The [Services Reference](/references/services/classes/AuthService) is an automatically generated API reference using Typedoc. So, you can’t contribute to it by making changes to its markdown files. You can, however, contribute to the script generating it if you find any issues in it. +--- + ## Style Guide When you contribute to the documentation content, make sure to follow the [documentation style guide](https://www.notion.so/Style-Guide-Docs-fad86dd1c5f84b48b145e959f36628e0). +--- + ## How to Contribute If you’re fixing errors in an existing documentation page, you can scroll down to the end of the page and click on the “Edit this page” link. You’ll be redirected to the GitHub edit form of that page and you can make edits directly and submit a pull request (PR). @@ -63,6 +73,8 @@ In the body of the PR, explain clearly what the PR does. If the PR solves an iss +--- + ## Sidebar When you add a new page to the documentation, you must add the new page in `www/docs/sidebars.js` under the `docsSidebar`. You can learn more about the syntax used [here](https://docusaurus.io/docs/sidebar/items). @@ -77,6 +89,8 @@ When the documentation page is tutorial documentation, the label in the sidebar The character count of the sidebar item's label must be at most twenty-seven characters. For the API Reference, the sidebar item's label must be at most twenty-five characters. +--- + ## Notes and Additional Information When displaying notes and additional information on a documentation page, use [Admonitions](https://docusaurus.io/docs/markdown-features/admonitions). Make sure the type of admonition used matches the note’s importance to the current document. @@ -89,10 +103,14 @@ If the note displays helpful information and tips use the `tip` admonition. If the admonition does not match any of the mentioned criteria, always default to the `note` admonition. +--- + ## Images If you are adding images to a documentation page, you can host the image on [Imgur](https://imgur.com) for free. +--- + ## Code Blocks ### Use Tabs with Code Blocks @@ -176,6 +194,8 @@ medusa new my-medusa-store --seed ``` ~~~ +--- + ## NPM and Yarn Code Blocks If you’re adding code blocks that use NPM and Yarn, you must use the [npm2yarn syntax](https://docusaurus.io/docs/markdown-features/code-blocks#npm2yarn-remark-plugin). @@ -216,6 +236,8 @@ When a command uses the global option `-g`, add it at the end of the NPM command npm install @medusajs/medusa-cli -g ``` +--- + ## Linting with Vale Medusa uses Vale to lint documentation pages and perform checks on incoming PRs into the repository. @@ -269,6 +291,8 @@ Medusa supports Node versions 14 and 16. If you use this in your PR, you must justify its usage. +--- + ## Need Additional Help If you need any additional help while contributing, you can join Medusa's [Discord server](https://discord.gg/medusajs) and ask Medusa’s core team as well as the community any questions. diff --git a/docs/content/deployments/admin/deploying-on-netlify.md b/docs/content/deployments/admin/deploying-on-netlify.md index 7ac9f41596..975c442e3f 100644 --- a/docs/content/deployments/admin/deploying-on-netlify.md +++ b/docs/content/deployments/admin/deploying-on-netlify.md @@ -35,6 +35,8 @@ If you want to use another Git Provider, it’s possible to follow along with th - Git’s CLI tool. You can follow [this documentation to learn how to install it for your operating system](../../tutorial/0-set-up-your-development-environment.mdx#git). +--- + ## Create GitHub Repository Before you can deploy your Medusa Admin you need to create a GitHub repository and push the code base to it. @@ -74,6 +76,8 @@ git push origin master After pushing the changes, you can find the files in your GitHub repository. +--- + ## Deploy to Netlify This section covers how to deploy Netlify either through the Netlify website or using Netlify’s CLI tool. @@ -236,7 +240,6 @@ For the rest of the steps, you can keep most of the default values provided by N ? Directory to deploy (blank for current dir): public ``` - #### Set Environment Variables After the previous command has finished running, your Netlify website will be created. The next step is to add an environment variable that points to your Medusa server. @@ -285,6 +288,8 @@ The Medusa Admin will then open in your browser. Before you can use Medusa Admin, you must add the URL as an environment variable on your deployed Medusa server. +--- + ## Configure CORS Variable on the Medusa Server To send requests to the Medusa server from the Medusa Admin, you must set the `ADMIN_CORS` environment variable on your server to the Medusa Admin’s URL. @@ -305,7 +310,9 @@ Where `` is the URL of your Medusa Admin that you just deployed. Then, restart your Medusa server. Once the server is running again, you can log in to the Medusa Admin and use it. -## What’s Next +--- -- Learn how to [deploy your storefront](../storefront/index.mdx). -- Learn more about [how you can configure Medusa](../../usage/configurations.md). +## See Also + +- [Deploy your storefront](../storefront/index.mdx) +- [Configure your Medusa server](../../usage/configurations.md) diff --git a/docs/content/deployments/server/deploying-on-digital-ocean.md b/docs/content/deployments/server/deploying-on-digital-ocean.md index 2a7eea41e9..5f1d6c18b3 100644 --- a/docs/content/deployments/server/deploying-on-digital-ocean.md +++ b/docs/content/deployments/server/deploying-on-digital-ocean.md @@ -31,6 +31,8 @@ If you want to use another Git Provider supported by DigitalOcean, it’s possib - Git’s CLI tool. You can follow [this documentation to learn how to install it for your operating system](../../tutorial/0-set-up-your-development-environment.mdx#git). +--- + ## Changes to package.json Change the `start` script in `package.json` to the following: @@ -41,6 +43,8 @@ Change the `start` script in `package.json` to the following: This ensures that Migrations are run everytime the Medusa server is restarted. +--- + ## Changes to medusa-config.js In `medusa-config.js`, the `DATABASE_URL` variable is set to the environment variable `DATABASE_URL`. This needs to be changed as DigitalOcean provides the different details of the database connection separately. @@ -68,6 +72,8 @@ module.exports = { }; ``` +--- + ## Create GitHub Repository Before you can deploy your Medusa server you need to create a GitHub repository and push the code base to it. @@ -107,6 +113,8 @@ git push origin master After pushing the changes, you can find the files in your GitHub repository. +--- + ## Deploy to DigitalOcean App After logging into your account, click on the Create button at the top right, then choose App. @@ -240,6 +248,8 @@ In the new page, click on the Previously Created DigitalOcean Database radio but Once you’re done click Attach Database. This will add the Redis database to the list of resources of your App and will trigger a redeploy of the App. +--- + ## Test your Server Once the redeployment is complete, copy the URL of the App which can be found under the App’s name. @@ -250,6 +260,8 @@ Then, go to `/store/products`. If the deployment was successful, y ![JSON response with list of products](https://res.cloudinary.com/dza7lstvk/image/upload/v1668002196/Medusa%20Docs/Digital%20Ocean/5xTdMbY_pqwyzy.png) +--- + ## Run Commands on Your Server To run commands on your server, you can access the console on the App’s page by choosing the Console tab. This opens a console in your browser where you can run commands on your server. @@ -265,6 +277,8 @@ Make sure to replace `` and `` with the credentials you want to ![Console in the DigitalOcean App](https://res.cloudinary.com/dza7lstvk/image/upload/v1668002204/Medusa%20Docs/Digital%20Ocean/9RMfD4C_u0mdqs.png) +--- + ## Add Environment Variables You’ll likely need to add environment variables later such as Admin Cross-Origin Resource Sharing (CORS) and Store CORS variables. @@ -279,7 +293,9 @@ Then, scroll down and find Environment Variables. You can expand the environment Once you click Save, the environment variables will be saved and a redeployment will be triggered. -## What’s Next +--- -- Learn [how to deploy the Medusa Admin to Netlify](../admin/deploying-on-netlify.md). -- Learn [how to deploy the Gatsby Storefront to Netlify](../storefront/deploying-gatsby-on-netlify.md). +## See Also + +- [Deploy the Medusa Admin to Netlify](../admin/deploying-on-netlify.md). +- [Deploy the Gatsby Storefront to Netlify](../storefront/deploying-gatsby-on-netlify.md). diff --git a/docs/content/deployments/server/deploying-on-heroku.mdx b/docs/content/deployments/server/deploying-on-heroku.mdx index 9794ecd4f7..2378efa73a 100644 --- a/docs/content/deployments/server/deploying-on-heroku.mdx +++ b/docs/content/deployments/server/deploying-on-heroku.mdx @@ -39,6 +39,8 @@ Furthermore, your Medusa server should be configured to work with PostgreSQL and - Git’s CLI tool. You can follow [this documentation to learn how to install it for your operating system](../../tutorial/0-set-up-your-development-environment.mdx#git). - Heroku's CLI tool. You can follow [Heroku's documentation to learn how to install it for your operating system](https://devcenter.heroku.com/articles/heroku-cli). +--- + ## Deploy to Heroku ### 1. Login to Heroku from your CLI @@ -238,6 +240,8 @@ heroku logs -n 500000 --remote heroku --tail -a Where `` is the name of the app. +--- + ## Run Commands on Your Server To run commands on your server, you can use the following command: @@ -256,6 +260,8 @@ heroku run -a -- medusa user -e "" -p "" Where `` is the name of your Heroku app, and `` and `` are the credentials you want to use to log in to the Medusa admin dashboard. +--- + ## Add Environment Variables You’ll likely need to add environment variables later such as Admin Cross-Origin Resource Sharing (CORS) and Store CORS variables. @@ -268,7 +274,9 @@ heroku config:set = -a Where `` is the name of your Heroku app, `` is the name of the environment variable, and `` is the value. -## What's Next +--- -- Learn how to [deploy your Medusa admin](../admin/index.mdx). -- Learn how to [deploy your storefront](../storefront/index.mdx). +## See Also + +- [Deploy your Medusa admin](../admin/index.mdx) +- [Deploy your storefront](../storefront/index.mdx) diff --git a/docs/content/deployments/server/deploying-on-qovery.md b/docs/content/deployments/server/deploying-on-qovery.md index 2bb204662c..20e094a7fc 100644 --- a/docs/content/deployments/server/deploying-on-qovery.md +++ b/docs/content/deployments/server/deploying-on-qovery.md @@ -42,6 +42,8 @@ If you want to use another [Git Provider supported by Qovery](https://hub.qovery - Terraform’s CLI tool. You can follow [this guide to install it based on your operating system](https://www.terraform.io/downloads). - Qovery’s CLI tool. You can follow [this guide to install it based on your operating system](https://hub.qovery.com/docs/using-qovery/interface/cli/#install). +--- + ## Create GitHub Repository Before you can deploy your Medusa server you need to create a GitHub repository and push the code base to it. @@ -81,6 +83,8 @@ git push origin master After pushing the changes, you can find the files in your GitHub repository. +--- + ## Deploy to Qovery In this section, you’ll learn how to deploy your Medusa server to Qovery with the help of Terraform. @@ -473,6 +477,8 @@ If you run into any errors while running this command, you can just re-run it af ::: +--- + ## Test your Server Once the command finishes and the deployment is successful, you can access your server in the [Qovery Console](https://console.qovery.com/). Go to the project, environment, then the app that you created using Terraform and Qovery. In the app, click the Open button at the top right to open your website in a new tab. @@ -481,6 +487,8 @@ Once the command finishes and the deployment is successful, you can access your You can access any of the endpoints on your server using the server URL. For example, you can get the list of products using the endpoint `/store/products`. +--- + ## Run Commands on Your Server To run commands on your server, run the following command: @@ -498,6 +506,8 @@ npm install @medusajs/medusa-cli -g medusa user --email --password ``` +--- + ## Add Environment Variables You’ll likely need to add environment variables later such as Admin Cross-Origin Resource Sharing (CORS) and Store CORS variables. @@ -506,7 +516,9 @@ To add environment variables, in your [Qovery Console](https://console.qovery.co ![Environment Variables in the sidebar](https://res.cloudinary.com/dza7lstvk/image/upload/v1668002258/Medusa%20Docs/Qovery/aQl7zdz_tjs0eb.png) -## What’s Next +--- -- Learn how to [deploy the Medusa Admin to Netlify](../admin/deploying-on-netlify.md). -- Learn how to [deploy the Gatsby Storefront to Netlify](../storefront/deploying-gatsby-on-netlify.md). +## See Also + +- [Deploy the Medusa Admin to Netlify](../admin/deploying-on-netlify.md) +- [Deploy the Gatsby Storefront to Netlify](../storefront/deploying-gatsby-on-netlify.md) diff --git a/docs/content/deployments/server/deploying-on-railway.md b/docs/content/deployments/server/deploying-on-railway.md index 3a23dec27c..65305be3e4 100644 --- a/docs/content/deployments/server/deploying-on-railway.md +++ b/docs/content/deployments/server/deploying-on-railway.md @@ -12,6 +12,8 @@ In this document, you’ll learn how to deploy your Medusa server to Railway. Railway provides a free plan that allows you to deploy your Medusa server along with PostgreSQL and Redis databases. This is useful mainly for development and demo purposes. +--- + ## Prerequisites ### Medusa Server @@ -29,12 +31,16 @@ Furthermore, your Medusa server should be configured to work with PostgreSQL and - Git’s CLI tool. You can follow [this documentation to learn how to install it for your operating system](./../../tutorial/0-set-up-your-development-environment.mdx#git). +--- + ## Changes to Medusa Server Codebase By default, Railway looks for a Dockerfile in the root of the codebase. If there is one, it will try to deploy your server using it. As this guide doesn't use Docker, make sure to delete `Dockerfile` from the root of your Medusa server. +--- + ## Create GitHub Repository Before you can deploy your Medusa server you need to create a GitHub repository and push the code base to it. @@ -74,6 +80,8 @@ git push origin master After pushing the changes, you can find the files in your GitHub repository. +--- + ## Deploy to Railway In this section, you’ll create the PostgreSQL and Redis databases first, then deploy the server from the GitHub repository. @@ -172,6 +180,8 @@ The last step is to add a domain name to your Medusa server. To do that: 2. Click on the Settings tab and scroll down to the Domains section. 3. Either click on the Custom Domain button to enter your own domain or the Generate Domain button to generate a random domain. +--- + ## Test your Server Every change you make to the settings redeploys the server. You can check the Deployments of the server by clicking on the GitHub repository’s card and choosing the Deployments tab. @@ -184,6 +194,8 @@ If you generated a random domain, you can find it by clicking on the GitHub repo ::: +--- + ## Troubleshooting If you run into any issues or a problem with your deployed server, you can check the logs in your Railway container instance by: @@ -192,13 +204,17 @@ If you run into any issues or a problem with your deployed server, you can check 2. Click on the Deployments tab. 3. Click on the View Logs button. +--- + ## Run Commands on Server To run commands on your server, 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 server to seed the database or create a new user using [Medusa’s CLI tool](../../cli/reference.md). -## What’s Next +--- -- Learn [how to deploy the Medusa Admin to Netlify](../admin/deploying-on-netlify.md). -- Learn [how to deploy the Gatsby Storefront to Netlify](../storefront/deploying-gatsby-on-netlify.md). +## See Also + +- [Deploy the Medusa Admin to Netlify](../admin/deploying-on-netlify.md) +- [Deploy the Gatsby Storefront to Netlify](../storefront/deploying-gatsby-on-netlify.md) diff --git a/docs/content/deployments/storefront/deploying-gatsby-on-netlify.md b/docs/content/deployments/storefront/deploying-gatsby-on-netlify.md index 7cc768d079..4c2905868e 100644 --- a/docs/content/deployments/storefront/deploying-gatsby-on-netlify.md +++ b/docs/content/deployments/storefront/deploying-gatsby-on-netlify.md @@ -12,6 +12,8 @@ Alternatively, you can use this button to deploy the Gatsby Storefront to Netlif Deploy to Netlify +--- + ## Prerequisites ### Medusa Components @@ -35,6 +37,8 @@ If you want to use another Git Provider, it’s possible to follow along with th - Git’s CLI tool. You can follow [this documentation to learn how to install it for your operating system](../../tutorial/0-set-up-your-development-environment.mdx#git). +--- + ## Create GitHub Repository Before you can deploy your Gatsby storefront you need to create a GitHub repository and push the code base to it. @@ -74,6 +78,8 @@ git push origin master After pushing the changes, you can find the files in your GitHub repository. +--- + ## Deploy to Netlify This section covers how to deploy Netlify either through the Netlify website or using Netlify’s CLI tool. @@ -291,6 +297,8 @@ The Gatsby storefront will then open in your browser. Before you can use the Gatsby storefront, you must add the URL as an environment variable on your deployed Medusa server. +--- + ## Configure CORS Variable on the Medusa Server To send requests to the Medusa server from the Gatsby storefront, you must set the `STORE_CORS` environment variable on your server to the Gatsby storefront’s URL. @@ -311,7 +319,9 @@ Where `` is the URL of your Gatsby storefront that you just depl Then, restart your Medusa server. Once the server is running again, you can use your Gatsby storefront. -## What’s Next +--- -- Learn how to [deploy the Medusa Admin](../admin/index.mdx). -- Learn more about [Medusa’s configurations](../../usage/configurations.md). +## See Also + +- [Deploy the Medusa Admin](../admin/index.mdx) +- [Configure your Medusa server](../../usage/configurations.md) diff --git a/docs/content/guides/carts-in-medusa.mdx b/docs/content/guides/carts-in-medusa.mdx index e49b22e9b3..ea466b68ee 100644 --- a/docs/content/guides/carts-in-medusa.mdx +++ b/docs/content/guides/carts-in-medusa.mdx @@ -21,6 +21,8 @@ This document does not cover implementing the checkout flow. You can refer to [t - **Line Item**: When products are added to the cart in Medusa, they are referred to as line items. Line items have, by default, the same properties and attributes as a product. However, you can customize line items specifically for a cart if necessary. +--- + ## Prerequisites ### Medusa Components @@ -35,6 +37,8 @@ This guide includes code snippets to send requests to your Medusa server using M If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client installed](../js-client/overview.md) and have [created an instance of the client](../js-client/overview.md#configuration). +--- + ## Create a Cart You can create a cart with the following code snippet: @@ -123,6 +127,8 @@ The region a cart is associated with determines the currency the cart uses, the ::: +--- + ## Retrieve a Cart Notice that in the previous code snippets, you set the cart’s ID in the local storage. This is helpful to persist the customer’s cart even when they leave the website and come back later. @@ -169,6 +175,8 @@ Make sure to remove the ID from the local storage after the customer places an o ::: +--- + ## Update a Cart A cart has different data associated with it including the region, email, address, customer, and more. @@ -288,6 +296,8 @@ fetch(`/store/carts/${cartId}`, { +--- + ## Add Line Item to the Cart To create a line item of a product and add it to a cart, you can use the following code snippet: @@ -337,6 +347,8 @@ If you’re using Sales Channels, make sure that the cart and the product belong ::: +--- + ## Update Line Item in the Cart To update a line item's quantity in the cart, you can use the following code snippet: @@ -376,6 +388,8 @@ This request accepts the ID of the cart and the ID of the line item as path para It returns the updated cart. +--- + ## Delete a Line Item from the Cart To delete a line item from the cart, you can use the following code snippet: @@ -407,7 +421,9 @@ This request accepts the ID of the cart and the ID of the line item as path para It returns the updated cart. -## What’s Next +--- -- Learn [how to implement the checkout flow in your storefront](../advanced/storefront/how-to-implement-checkout-flow.mdx). -- Learn more about the [JS Client and how to use it](../js-client/overview.md). +## See Also + +- [Implement the checkout flow in your storefront](../advanced/storefront/how-to-implement-checkout-flow.mdx) +- [Medusa JS Client Overview](../js-client/overview.md) diff --git a/docs/content/js-client/overview.md b/docs/content/js-client/overview.md index c2c96d617c..2589323304 100644 --- a/docs/content/js-client/overview.md +++ b/docs/content/js-client/overview.md @@ -12,6 +12,8 @@ To install the Medusa JS Client run the following command: npm install @medusajs/medusa-js ``` +--- + ## Usage Import Medusa as a default import and initiate it: @@ -22,6 +24,8 @@ import Medusa from "@medusajs/medusa-js" const medusa = new Medusa() ``` +--- + ## How to Use this Reference You'll find in the sidebar of this reference names of different resources. These resources are properties in the medusa instance you initialize and you can access them directly using the instance. Then, you'll be able to access the methods or nested resources within those resources. @@ -47,6 +51,8 @@ medusa.customers.addresses.addAddress({ }) ``` +--- + ## Authentication Authentication can be achieved in two ways using the `medusa-js` client: either by utilizing API keys or by using cookie based authentication. Each method has its own unique use case. @@ -59,6 +65,8 @@ API keys can only be used for admin functionality in Medusa since only users of Authentication using cookies is done automatically by Axios when authenticating using the [auth](/references/js-client/classes/AuthResource) endpoints. After authentication, all subsequent calls will be authenticated. +--- + ## Configuration ### Initialize with config object diff --git a/docs/content/nav.yml b/docs/content/nav.yml deleted file mode 100644 index 9a16383e66..0000000000 --- a/docs/content/nav.yml +++ /dev/null @@ -1,41 +0,0 @@ -- title: Tutorials - id: tutorials - items: - - id: overview - title: Overview - - id: getting-started - title: Getting started - - id: adding-plugins - title: Adding plugins - - id: creating-a-custom-endpoint - title: Creating a custom endpoint - - id: linking-medusa-cloud - title: Linking Medusa Cloud -- title: Guides - id: guides - items: - - id: overview - title: Overview - - id: local-development - title: Local development - items: - - id: overview - title: Overview - - id: create-project-from-starter - title: Create project from starter - items: - - id: medusa-starter - title: Medusa starter - - id: gatsby-starter-medusa - title: Gatsby starter - - id: environment-variables - title: Environment variables -- title: Reference - id: reference - items: - - id: admin - title: admin - - id: store - title: store -- title: Contributing - id: contributing diff --git a/docs/content/quickstart/quick-start-docker.mdx b/docs/content/quickstart/quick-start-docker.mdx index 96d34db878..c245445e51 100644 --- a/docs/content/quickstart/quick-start-docker.mdx +++ b/docs/content/quickstart/quick-start-docker.mdx @@ -19,6 +19,8 @@ You can install Node from the [official website](https://nodejs.org/en/). It is assumed that you have Docker installed on your system. You can install it from [Docker's website](https://docs.docker.com/get-docker/). +--- + ## Create Medusa Server with Docker ### 1. Clone Medusa's starter project from GitHub @@ -70,6 +72,8 @@ Running the above command does the following: negativeQuestion="Please describe the issue you faced." /> +--- + ## Test Your Server Once done, your server will be accessible at `http://localhost:9000`. @@ -90,6 +94,8 @@ curl localhost:9000/store/products ::: +--- + ## Additional steps ### File Service Plugin @@ -106,7 +112,9 @@ It's important to configure your Medusa server properly and learn how environmen You can learn more about configuring your server and loading environment variables in the [Configure your Server documentation](../usage/configurations.md). -## What's Next +--- + +## See Also - Install the [Next.js](../starters/nextjs-medusa-starter.mdx) or [Gatsby](../starters/gatsby-medusa-starter.mdx) storefronts to set up your ecommerce storefront quickly. - Install the [Medusa Admin](../admin/quickstart.mdx) to supercharge your ecommerce experience with easy access to configurations and features. diff --git a/docs/content/quickstart/quick-start.mdx b/docs/content/quickstart/quick-start.mdx index 124ad05567..2d42b23c2c 100644 --- a/docs/content/quickstart/quick-start.mdx +++ b/docs/content/quickstart/quick-start.mdx @@ -14,6 +14,8 @@ node -v You can install Node from the [official website](https://nodejs.org/en/). +--- + ## Create a Medusa Server :::tip @@ -72,6 +74,8 @@ curl localhost:9000/store/products ::: +--- + ## Additional Steps ### Set Up Development Environment @@ -94,7 +98,9 @@ To upload product images to your Medusa server, you must install and configure o - [S3](../add-plugins/s3.md) - [DigitalOcean Spaces](../add-plugins/spaces.md) -## What's Next +--- + +## See Also - Install the [Next.js](../starters/nextjs-medusa-starter.mdx) or [Gatsby](../starters/gatsby-medusa-starter.mdx) storefronts to set up your ecommerce storefront. - Install the [Medusa Admin](../admin/quickstart.mdx) to supercharge your ecommerce experience with easy access to configurations and features. diff --git a/docs/content/starters/gatsby-medusa-starter.mdx b/docs/content/starters/gatsby-medusa-starter.mdx index ce88ab61ce..e193b3298b 100644 --- a/docs/content/starters/gatsby-medusa-starter.mdx +++ b/docs/content/starters/gatsby-medusa-starter.mdx @@ -14,6 +14,8 @@ Instead of manually following this guide to install then later deploy the Gatsby Deploy to Netlify +--- + ## Prerequisites This document assumes you already have a Medusa server installed. If you don’t, please follow the [Quickstart guide for the Medusa server](../quickstart/quick-start.mdx) to learn how to do it. @@ -24,6 +26,8 @@ You should also have the Gatsby CLI installed: npm install gatsby-cli -g ``` +--- + ## Installation :::tip @@ -60,6 +64,8 @@ Your Gatsby storefront is now running at `localhost:8000`! negativeQuestion="Please describe the issue you faced." /> +--- + ## Development Notes ### Customization @@ -107,6 +113,8 @@ If you’re not familiar with Gatsby, you can learn more about it through the fo - [Plugin Library](https://www.gatsbyjs.com/plugins/) - [Cheat Sheet](https://www.gatsbyjs.com/docs/cheat-sheet/) +--- + ## Storefront Features The Gatsby storefront comes with a lot of features out of the box including: @@ -124,8 +132,10 @@ The Gatsby storefront comes with a lot of features out of the box including: ![Request Return for Order](https://res.cloudinary.com/dza7lstvk/image/upload/v1668003162/Medusa%20Docs/Screenshots/mAChp3f_ubd89n.png) -## What’s Next +--- -- Check the [Storefront API reference](https://docs.medusajs.com/api/store) for a full list of REST APIs to use on your storefront. -- Learn how to [deploy the Gatsby storefront on Netlify](../deployments/storefront/deploying-gatsby-on-netlify.md). -- Learn how to add [Stripe as a payment provider](../add-plugins/stripe.md#gatsby-storefront). +## See Also + +- [Storefront API reference](https://docs.medusajs.com/api/store) +- [Deploy the Gatsby storefront on Netlify](../deployments/storefront/deploying-gatsby-on-netlify.md) +- [Install Stripe as a payment provider](../add-plugins/stripe.md#add-to-gatsby-storefront) diff --git a/docs/content/starters/nextjs-medusa-starter.mdx b/docs/content/starters/nextjs-medusa-starter.mdx index 62bd521696..cbfa73a2dc 100644 --- a/docs/content/starters/nextjs-medusa-starter.mdx +++ b/docs/content/starters/nextjs-medusa-starter.mdx @@ -14,10 +14,14 @@ Instead of manually following this guide to install then later deploy the Next.j Deploy to Netlify +--- + ## Prerequisites This document assumes you already have a Medusa server installed. If you don’t, please follow the [Quickstart guide for the Medusa server](../quickstart/quick-start.mdx) to learn how to do it. +--- + ## Installation :::tip @@ -54,6 +58,8 @@ Your Next.js storefront is now running at `localhost:8000`! negativeQuestion="Please describe the issue you faced." /> +--- + ## Development Notes ### Toggle Search Engine Feature @@ -215,6 +221,8 @@ STORE_CORS=http://localhost: You can learn more about development with Next.js through [their documentation](https://nextjs.org/docs/getting-started). +--- + ## Storefront Features - View all products and manage your cart. @@ -229,7 +237,10 @@ You can learn more about development with Next.js through [their documentation]( ![Checkout Page](https://res.cloudinary.com/dza7lstvk/image/upload/v1668003296/Medusa%20Docs/Screenshots/VC8SYfb_eowjno.png) -## What’s Next +--- -- Check the [Storefront API reference](https://docs.medusajs.com/api/store) for a full list of REST APIs to use on your storefront. -- Learn [how to install Medusa Admin](../admin/quickstart.mdx). +## See Also + +- [Storefront API reference](https://docs.medusajs.com/api/store) +- [Install Medusa Admin](../admin/quickstart.mdx). +- [Install Stripe as a payment provider](../add-plugins/stripe.md#add-to-nextjs-storefront) diff --git a/docs/content/troubleshooting/cli-installation-errors.mdx b/docs/content/troubleshooting/cli-installation-errors.mdx index 63a4d488e4..78712d5234 100644 --- a/docs/content/troubleshooting/cli-installation-errors.mdx +++ b/docs/content/troubleshooting/cli-installation-errors.mdx @@ -11,6 +11,8 @@ If you install the Medusa CLI tool with NPM and get a permission error, NPM prop You can check out more information in [NPM’s documentation](https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally). +--- + ## Yarn Error: command not found: medusa diff --git a/docs/content/troubleshooting/cors-issues.md b/docs/content/troubleshooting/cors-issues.md index 5119d8b18d..9895e65a33 100644 --- a/docs/content/troubleshooting/cors-issues.md +++ b/docs/content/troubleshooting/cors-issues.md @@ -20,6 +20,8 @@ const STORE_CORS = process.env.STORE_CORS || "http://localhost:8000" If you wish to run your storefront or Medusa admin on other ports, you should update the above settings accordingly. -## Additional Resources +--- -To learn more about CORS configurations, check out the [Configure your Server](../usage/configurations.md) documentation. +## See Also + +- [Configure your Medusa server](../usage/configurations.md) diff --git a/docs/content/troubleshooting/documentation-error.md b/docs/content/troubleshooting/documentation-error.md index 94fbcd525f..cc31b8e5e3 100644 --- a/docs/content/troubleshooting/documentation-error.md +++ b/docs/content/troubleshooting/documentation-error.md @@ -8,6 +8,8 @@ This is because the content resides in `docs/content`. When that content is bein For that reason, when the `start` and `build` scripts in `www/docs` are used, the `clean-node-modules` script is called. This script deleted the `node_modules` directory in the root of the Medusa repository. +--- + ## Out of Memory Error If you receive the following error when you run the `build` command in `www/docs`: diff --git a/docs/content/troubleshooting/missing-payment-providers.md b/docs/content/troubleshooting/missing-payment-providers.md index 9e7feaf6db..ed3a26f0da 100644 --- a/docs/content/troubleshooting/missing-payment-providers.md +++ b/docs/content/troubleshooting/missing-payment-providers.md @@ -27,7 +27,9 @@ However, to also show them as part of your checkout flow you need to add them to In the Medusa Admin go to Settings > Regions and for each region scroll down to the Payment Provider input and choose the payment provider you want to use in that region. -## Additional Resources +--- -- Learn how to install [Stripe](../add-plugins/stripe.md) as a payment provider. -- Learn more about the [Payment architecture](../advanced/backend/payment/overview.md). +## See Also + +- [Install Stripe](../add-plugins/stripe.md) +- [Payment Architecture Overview](../advanced/backend/payment/overview.md) diff --git a/docs/content/troubleshooting/redis-events.md b/docs/content/troubleshooting/redis-events.md index c8342b92bf..30140eb6d6 100644 --- a/docs/content/troubleshooting/redis-events.md +++ b/docs/content/troubleshooting/redis-events.md @@ -23,7 +23,9 @@ By default, Medusa connects to Redis over the URL `redis://localhost:6379`. If y REDIS_URL= ``` -## Additional Resources +--- -- Learn how to [set up your development environment](../tutorial/0-set-up-your-development-environment.mdx). -- Learn how to [configure your server](../usage/configurations.md). +## See Also + +- [Set up your development environment](../tutorial/0-set-up-your-development-environment.mdx) +- [Configure your server](../usage/configurations.md) diff --git a/docs/content/troubleshooting/signing-in-to-admin.md b/docs/content/troubleshooting/signing-in-to-admin.md index 0089558b3c..aa8a389f24 100644 --- a/docs/content/troubleshooting/signing-in-to-admin.md +++ b/docs/content/troubleshooting/signing-in-to-admin.md @@ -13,6 +13,8 @@ Alternatively, you can create your own users using the Medusa CLI tool: medusa user -e some@email.com -p somepassword ``` -## Additional Resources +--- -Learn more about Medusa's CLI tool in the [CLI reference](../cli/reference.md). +## See Also + +- [Medusa CLI tool reference](../cli/reference.md) diff --git a/docs/content/troubleshooting/transaction-error-in-checkout.md b/docs/content/troubleshooting/transaction-error-in-checkout.md index 6830f67d24..bc9d555fe3 100644 --- a/docs/content/troubleshooting/transaction-error-in-checkout.md +++ b/docs/content/troubleshooting/transaction-error-in-checkout.md @@ -52,8 +52,10 @@ npm run seed ::: -## Additional Resources +--- -- Learn how to [set up your development environment](../tutorial/0-set-up-your-development-environment.mdx). -- Learn how to [configure your server](../usage/configurations.md). -- Learn more about [the Medusa CLI tool](../cli/reference.md). +## See Also + +- [Set up your development environment](../tutorial/0-set-up-your-development-environment.mdx) +- [Configure your server](../usage/configurations.md) +- [Medusa CLI tool reference](../cli/reference.md) diff --git a/docs/content/tutorial/0-set-up-your-development-environment.mdx b/docs/content/tutorial/0-set-up-your-development-environment.mdx index 355809795d..c6847bed28 100644 --- a/docs/content/tutorial/0-set-up-your-development-environment.mdx +++ b/docs/content/tutorial/0-set-up-your-development-environment.mdx @@ -139,6 +139,8 @@ If you run into any errors while installing the CLI tool, check out the [trouble ::: +--- + ## Optional Tools These tools are not required to have to run a Medusa server, but it's highly recommended that you have them installed. @@ -268,8 +270,10 @@ To install Redis without Homebrew you can check out [Redis’s guide on installi -## What’s Next +--- -- Learn how to [configure your Medusa server](../usage/configurations.md). -- Learn how to install a storefront with [Next.js](../starters/nextjs-medusa-starter.mdx) or [Gatsby](./../starters/gatsby-medusa-starter.mdx). -- Learn how to install the [Medusa Admin](../admin/quickstart.mdx). +## See Also + +- [Configure your Medusa server](../usage/configurations.md). +- Install a storefront with [Next.js](../starters/nextjs-medusa-starter.mdx) or [Gatsby](./../starters/gatsby-medusa-starter.mdx). +- [Install the Medusa Admin](../admin/quickstart.mdx). diff --git a/docs/content/usage.md b/docs/content/usage.md index 0c61986283..f64b0f22d3 100644 --- a/docs/content/usage.md +++ b/docs/content/usage.md @@ -9,6 +9,8 @@ This document gives an overview of Medusa’s optional collected usage informati At Medusa, we strive to provide the best experience for developers using our platform. For that reason, Medusa collects anonymous and non-sensitive data that provides a global understanding of how users are using Medusa. +--- + ## Purpose As an open source solution, we work closely and constantly interact with our community to ensure that we provide the best experience for everyone using Medusa. @@ -25,6 +27,8 @@ Collecting this data allows us to understand certain details such as: - How much data do users manage through our Medusa Admin? Is it being used for large number of products, orders, and other types of data? - What Node version is globally used? Should we focus our efforts on providing support for versions that we don’t currently support? +--- + ## Server Analytics This section covers which data in the server are collected and how to opt out of it. @@ -58,6 +62,8 @@ Or, you can run the following command in the root of your Medusa server project medusa telemetry --disable ``` +--- + ## Admin Analytics This section covers which data in the admin are collected and how to opt out of it. diff --git a/docs/content/usage/configurations.md b/docs/content/usage/configurations.md index 04fefecc57..1ad4a834a6 100644 --- a/docs/content/usage/configurations.md +++ b/docs/content/usage/configurations.md @@ -6,12 +6,16 @@ In this document, you’ll learn what configurations you can add to your Medusa This document assumes you already followed along with the [“Set up your development environment” documentation](../tutorial/0-set-up-your-development-environment.mdx) and have [installed a Medusa server](../quickstart/quick-start.mdx#create-a-medusa-server). +--- + ## Medusa Configurations File The configurations for your Medusa server are in `medusa-config.js`. This includes database, Redis, and plugin configurations, among other configurations. Some of the configurations mentioned in this document are already defined in `medusa-config.js` with default values. It’s important that you know what these configurations are used for and how to set them. +--- + ## Environment Variables In your configurations, you’ll often use environment variables. For example, when using API keys or setting your database URL. @@ -24,6 +28,8 @@ This change in how environment variables are loaded was introduced in version 1. ::: +--- + ## Database Configuration Medusa supports two database types: SQLite and PostgreSQL. @@ -110,6 +116,8 @@ module.exports = { }; ``` +--- + ## Redis Medusa uses Redis to handle the event queue, among other usages. You need to set Redis URL in the configurations: @@ -147,6 +155,8 @@ You can learn more about Subscribers and events in the [Subscriber documentation ::: +--- + ## JWT Secret Medusa uses JSON Web Token (JWT) to handle user authentication. To set the JWT secret: @@ -176,6 +186,8 @@ In a development environment, if this option is not set the default secret is ::: +--- + ## Cookie Secret This configuration is used to sign the session ID cookie. To set the cookie secret: @@ -205,6 +217,8 @@ In a development environment, if this option is not set the default secret is ::: +--- + ## CORS Configurations Medusa uses Cross-Origin Resource Sharing (CORS) to only allow specific origins to access the server. @@ -276,6 +290,8 @@ Make sure that the URL is without a backslash at the end. For example, you shoul ::: +--- + ## Plugins On your Medusa server, you can use Plugins to add custom features or integrate third-party services. For example, installing a plugin to use Stripe as a payment provider. @@ -330,8 +346,10 @@ It is recommended to use environment variables to store values of options instea ::: -## What’s Next +--- -- Check out the [Next.js](../starters/nextjs-medusa-starter.mdx) and [Gatsby](../starters/gatsby-medusa-starter.mdx) starter storefronts. -- Install the [Medusa admin](../admin/quickstart.mdx). -- Learn about [deploying the Medusa server](../deployments/server/index.mdx). +## See Also + +- Check out the [Next.js](../starters/nextjs-medusa-starter.mdx) and [Gatsby](../starters/gatsby-medusa-starter.mdx) starter storefronts +- [Install the Medusa admin](../admin/quickstart.mdx) +- [Deploy the Medusa server](../deployments/server/index.mdx) diff --git a/docs/content/usage/create-medusa-app.mdx b/docs/content/usage/create-medusa-app.mdx index dc30d143fa..adff4da8cd 100644 --- a/docs/content/usage/create-medusa-app.mdx +++ b/docs/content/usage/create-medusa-app.mdx @@ -15,6 +15,8 @@ However, if you’re interested in using Medusa’s starters for the three compo When you run the `create-medusa-app` command, you’ll install a Medusa server, a Medusa admin, and optionally a storefront at the same time. +--- + ## How to Create a Medusa Project In your terminal, run the following command: @@ -103,6 +105,8 @@ yarn start The commands will differ based on your choices in previous prompts. +--- + ## Project Directory Structure Inside the root project directory which was specified at the beginning of the installation process you’ll find the following directory structure: @@ -114,8 +118,10 @@ Inside the root project directory which was specified at the beginning of the in /admin // Medusa admin panel ``` +--- + ## What’s Next -- Learn how to [deploy the Medusa server](../deployments/server/index.mdx). -- Learn how to [deploy the Medusa admin](../deployments/admin/index.mdx). -- Learn how to [deploy the storefront](../deployments/storefront/index.mdx). \ No newline at end of file +- [Deploy the Medusa server](../deployments/server/index.mdx) +- [Deploy the Medusa admin](../deployments/admin/index.mdx) +- [Deploy the storefront](../deployments/storefront/index.mdx) diff --git a/docs/content/usage/local-development.md b/docs/content/usage/local-development.md index 9b52873033..373c35f84f 100644 --- a/docs/content/usage/local-development.md +++ b/docs/content/usage/local-development.md @@ -14,6 +14,8 @@ Whether you want to implement something differently, introduce a new future as p All the packages are part of a [Yarn workspace](https://classic.yarnpkg.com/lang/en/docs/workspaces/). So, when you run a command in the root of the project, such as `yarn build`, it goes through all registered packages in the workspace under the `packages` directory and runs the `build` command in each of those packages. +--- + ## Prerequisites ### Yarn @@ -51,6 +53,8 @@ In the directory of your forked GitHub repository, run the following command to medusa-dev --set-path-to-repo `pwd` ``` +--- + ## Run Tests in the Repository In this section, you’ll learn how to run tests in the Medusa repository. This is helpful after you customize any of Medusa’s packages and want to make sure everything is still working as expected. @@ -94,6 +98,8 @@ To run the plugin integration tests, run the following command in the root direc yarn test:integration:plugins ``` +--- + ## Test in a Local Server Using Medusa’s dev CLI tool, you can test any changes you make to Medusa’s packages in a local server installation. This eliminates the need to publish these packages on NPM publicly to be able to use them. @@ -146,7 +152,9 @@ medusa-dev -q medusa-dev --packages @medusajs/medusa-cli medusa-file-minio ``` -## What’s Next +--- -- Check out our [contribution guidelines](https://github.com/medusajs/medusa/blob/master/CONTRIBUTING.md). -- Learn how to [create a plugin](../advanced/backend/plugins/create.md). +## See Also + +- [Create a Plugin](../advanced/backend/plugins/create.md) +- [Contribution Guidelines](https://github.com/medusajs/medusa/blob/master/CONTRIBUTING.md)