docs: various improvements and fixes (#14257)
This commit is contained in:
Shahed Nasser authored and 
GitHub committed
1 parent
75eac9ebec
commit
0084460765
25 files changed
+141626
-131305
No files matched your search
@@ -8,7 +8,7 @@ export const metadata = {
|
||||
|
||||
In this section of the documentation, you'll find guides and references related to Medusa's Commerce Modules.
|
||||
|
||||
A Commerce Module provides features for a commerce domain within its service. The Medusa application exposes these features in its API routes to clients.
|
||||
A Commerce Module provides features for a commerce domain within its service. When you install the Medusa application, all Commerce Modules are available out-of-the-box. The Medusa application exposes their features in its core API routes to clients.
|
||||
|
||||
A Commerce Module also defines data models, representing tables in the database. The Medusa Framework and tools allow you to extend these data models to add custom fields.
|
||||
|
||||
@@ -97,6 +97,6 @@ A Commerce Module also defines data models, representing tables in the database.
|
||||
|
||||
The Commerce Modules can be used in many use cases, including:
|
||||
|
||||
- Medusa Application: The Medusa application uses the Commerce Modules to expose commerce features through the REST APIs.
|
||||
- Medusa Application: The Medusa application comes with all Commerce Modules pre-installed and configured. Their commerce features are exposed through REST APIs.
|
||||
- Serverless Application: Use the Commerce Modules in a serverless application, such as a Next.js application, without having to manage a fully-fledged ecommerce system. You can use it by installing it in your Node.js project as an NPM package.
|
||||
- Node.js Application: Use the Commerce Modules in any Node.js application by installing it with NPM.
|
||||
@@ -29,7 +29,7 @@ Learn more about why modules are isolated in [this documentation](!docs!/learn/f
|
||||
## Store Features
|
||||
|
||||
- [Store Management](/references/store/models/Store): Create and manage stores in your application.
|
||||
- [Multi-Tenancy Support](/references/store/models/Store): Create multiple stores, each having its own configurations.
|
||||
- [Multi-Tenancy Support](/references/store/models/Store): While Medusa doesn't natively support multi-tenancy, the Store Module allows you to create and manage multiple stores within a single Medusa instance. You can then build customizations to link products, customers, orders, and other resources to specific stores.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -628,7 +628,7 @@ const StripeSavedPaymentMethodsContainer = ({
|
||||
await initiatePaymentSession(cart, {
|
||||
provider_id: method.provider_id,
|
||||
data: {
|
||||
payment_method_id: method.id,
|
||||
payment_method: method.id,
|
||||
},
|
||||
}).catch((error) => {
|
||||
setError(error.message)
|
||||
|
||||
@@ -58,8 +58,8 @@ module.exports = defineConfig({
|
||||
// keep jobs for 1 hour or up to 1000 jobs
|
||||
age: 3600,
|
||||
count: 1000,
|
||||
}
|
||||
}
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
],
|
||||
|
||||
@@ -29,7 +29,7 @@ These guides are for developers who want to build a storefront for their Medusa
|
||||
|
||||
All guides under this documentation section use the [JS SDK](../js-sdk/page.mdx) to interact with the Medusa application's Store API Routes. The JS SDK is a NPM package that facilitates interacting with the backend's REST APIs. You can use it in any JavaScript framework, such as Next.js, React, Vue, or Angular.
|
||||
|
||||
To install and set up the JS SDK, refer to the [JS SDK documentation](../js-sdk/page.mdx).
|
||||
Refer to the [Connect to the Medusa Application](./tips/page.mdx) guide to learn how to set up the JS SDK in your storefront application.
|
||||
|
||||
### Not Using JavaScript?
|
||||
|
||||
|
||||
@@ -30,7 +30,7 @@ Learn how to install and configure the JS SDK in the [JS SDK documentation](../.
|
||||
<CodeTab label="React" value="react">
|
||||
|
||||
export const highlights = [
|
||||
["17"], ["18"], ["19"], ["20"], ["21"]
|
||||
["18"], ["19"], ["20"], ["21"], ["22"]
|
||||
]
|
||||
|
||||
```tsx highlights={highlights}
|
||||
@@ -38,6 +38,7 @@ export const highlights = [
|
||||
|
||||
import { useEffect, useState } from "react"
|
||||
import { HttpTypes } from "@medusajs/types"
|
||||
import { sdk } from "@/lib/sdk"
|
||||
|
||||
export default function Products() {
|
||||
const [loading, setLoading] = useState(true)
|
||||
|
||||
@@ -70,6 +70,17 @@ Make sure to replace `apk_123` with the ID of the publishable API key, and `sc_1
|
||||
|
||||
In your storefront, pass the `x-publishable-api-key` in the header of all your requests to the Medusa application.
|
||||
|
||||
For example:
|
||||
|
||||
```bash
|
||||
curl '{backend_url}/store/products' \
|
||||
-H 'x-publishable-api-key: {your_publishable_api_key}'
|
||||
```
|
||||
|
||||
Where `{your_publishable_api_key}` is the token of your publishable API key.
|
||||
|
||||
### Using the JS SDK
|
||||
|
||||
When using the JS SDK, set the publishable API key as an environment variable and pass it to the JS SDK's configurations.
|
||||
|
||||
For example:
|
||||
@@ -94,6 +105,6 @@ export const sdk = new Medusa({
|
||||
})
|
||||
```
|
||||
|
||||
Where `NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY` is an environment variable that holds your publishable API key's token.
|
||||
Where `NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY` is an environment variable that holds your publishable API key's token. Based on your storefront framework, make sure the environment variable is accessible in the browser. For example, in Next.js, prefix the variable name with `NEXT_PUBLIC_`.
|
||||
|
||||
The JS SDK will now take care of passing the publishable API key in the header of all requests to the Medusa application.
|
||||
@@ -4,12 +4,12 @@ tags:
|
||||
---
|
||||
|
||||
export const metadata = {
|
||||
title: `Storefront Development Tips`,
|
||||
title: `Connect Your Storefront to Medusa`,
|
||||
}
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
In this document, you’ll find tips useful when building a storefront.
|
||||
In this guide, you’ll learn how to send requests from your storefront application to the Medusa application.
|
||||
|
||||
## Connect to the Medusa Application
|
||||
|
||||
@@ -18,34 +18,68 @@ To send requests from the storefront to the Medusa application’s Store API Rou
|
||||
- **For JavaScript frameworks**: use Medusa’s [JS SDK](../../js-sdk/page.mdx) in any JavaScript framework. This NPM package facilitates interacting with the backend’s REST APIs. All Storefront Development guides use the JS SDK.
|
||||
- **For other frontend technologies**: interact directly with the Medusa application by sending requests to its [Store REST APIs](https://docs.medusajs.com/api/store).
|
||||
|
||||
---
|
||||
### Set Up the JS SDK
|
||||
|
||||
## Install Types Package
|
||||
|
||||
The `@medusajs/types` package provide API routes' request and response types.
|
||||
|
||||
If you're not using the JS SDK but are building your application with TypeScript, install `@medusajs/types` to use the correct request and response types:
|
||||
To set up the JS SDK in your storefront application, install the `@medusajs/js-sdk` package with the types package:
|
||||
|
||||
```bash npm2yarn
|
||||
npm install @medusajs/types@latest
|
||||
npm install @medusajs/js-sdk@latest @medusajs/types@latest
|
||||
```
|
||||
|
||||
Then, create a file that initializes the JS SDK client. For example, create the file `src/lib/sdk.ts` with the following content:
|
||||
|
||||
```ts title="src/lib/sdk.ts"
|
||||
import Medusa from "@medusajs/js-sdk"
|
||||
|
||||
let MEDUSA_BACKEND_URL = "http://localhost:9000"
|
||||
|
||||
if (process.env.NEXT_PUBLIC_MEDUSA_BACKEND_URL) {
|
||||
MEDUSA_BACKEND_URL = process.env.NEXT_PUBLIC_MEDUSA_BACKEND_URL
|
||||
}
|
||||
|
||||
export const sdk = new Medusa({
|
||||
baseUrl: MEDUSA_BACKEND_URL,
|
||||
debug: process.env.NODE_ENV === "development",
|
||||
publishableKey: process.env.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY,
|
||||
})
|
||||
```
|
||||
|
||||
Where:
|
||||
|
||||
- `NEXT_PUBLIC_MEDUSA_BACKEND_URL` is the URL of your Medusa application. Based on your storefront framework, make sure the environment variable is accessible in the browser. For example, in Next.js, prefix the variable name with `NEXT_PUBLIC_`.
|
||||
- `NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY` is the publishable API key of your storefront. Learn more in the [Publishable API Keys](../publishable-api-keys/page.mdx) guide.
|
||||
|
||||
You can then import the `sdk` instance from `src/lib/sdk.ts` and use it to send requests to the Medusa application. For example:
|
||||
|
||||
```ts
|
||||
import { sdk } from "@/lib/sdk"
|
||||
|
||||
sdk.store.product.list()
|
||||
.then(({ products }) => {
|
||||
console.log(products)
|
||||
})
|
||||
```
|
||||
|
||||
Refer to the [JS SDK reference](../../js-sdk/page.mdx) to learn more about using the SDK to interact with the Medusa application.
|
||||
|
||||
---
|
||||
|
||||
## Configure CORS
|
||||
## Configure Store CORS in Medusa
|
||||
|
||||
The Medusa application’s API routes are guarded by a CORS middleware. Make sure to set the `storeCors` property of the `http` configuration in `medusa-config.ts` to the storefront’s URL.
|
||||
|
||||
For example:
|
||||
|
||||
```ts title="medusa-config.ts"
|
||||
```ts title="medusa-config.ts" badgeLabel="Medusa Application" badgeColor="green"
|
||||
module.exports = defineConfig({
|
||||
projectConfig: {
|
||||
http: {
|
||||
storeCors: "http://localhost:3000",
|
||||
storeCors: "http://localhost:3000,http://localhost:8000",
|
||||
// ...
|
||||
},
|
||||
},
|
||||
// ...
|
||||
})
|
||||
```
|
||||
|
||||
Refer to the [Medusa configuration](!docs!/learn/configurations/medusa-config#httpstorecors) guide to learn more about configuring CORS in the Medusa application.
|
||||
@@ -85,7 +85,7 @@ export const generatedEditDates = {
|
||||
"app/commerce-modules/stock-location/page.mdx": "2025-04-17T08:48:26.441Z",
|
||||
"app/commerce-modules/store/_events/_events-table/page.mdx": "2024-07-03T19:27:13+03:00",
|
||||
"app/commerce-modules/store/_events/page.mdx": "2024-07-03T19:27:13+03:00",
|
||||
"app/commerce-modules/store/page.mdx": "2025-04-17T08:48:34.141Z",
|
||||
"app/commerce-modules/store/page.mdx": "2025-12-09T10:56:06.938Z",
|
||||
"app/commerce-modules/tax/_events/_events-table/page.mdx": "2024-07-03T19:27:13+03:00",
|
||||
"app/commerce-modules/tax/_events/page.mdx": "2024-07-03T19:27:13+03:00",
|
||||
"app/commerce-modules/tax/module-options/page.mdx": "2025-05-20T07:51:40.711Z",
|
||||
@@ -98,7 +98,7 @@ export const generatedEditDates = {
|
||||
"app/commerce-modules/user/module-options/page.mdx": "2025-10-31T10:08:14.831Z",
|
||||
"app/commerce-modules/user/user-creation-flows/page.mdx": "2025-02-26T11:35:54.685Z",
|
||||
"app/commerce-modules/user/page.mdx": "2025-04-17T08:48:17.980Z",
|
||||
"app/commerce-modules/page.mdx": "2025-04-17T08:48:34.855Z",
|
||||
"app/commerce-modules/page.mdx": "2025-12-09T10:58:53.037Z",
|
||||
"app/create-medusa-app/page.mdx": "2025-07-14T08:51:06.654Z",
|
||||
"app/deployment/admin/vercel/page.mdx": "2024-10-16T08:10:29.377Z",
|
||||
"app/deployment/storefront/vercel/page.mdx": "2025-05-20T07:51:40.712Z",
|
||||
@@ -163,7 +163,7 @@ export const generatedEditDates = {
|
||||
"app/storefront-development/products/collections/products/page.mdx": "2025-03-27T14:46:51.466Z",
|
||||
"app/storefront-development/products/collections/retrieve/page.mdx": "2025-03-27T14:46:51.458Z",
|
||||
"app/storefront-development/products/collections/page.mdx": "2024-06-11T19:55:56+02:00",
|
||||
"app/storefront-development/products/list/page.mdx": "2025-03-27T14:46:51.431Z",
|
||||
"app/storefront-development/products/list/page.mdx": "2025-12-09T13:32:29.583Z",
|
||||
"app/storefront-development/products/price/examples/sale-price/page.mdx": "2025-03-27T14:47:14.308Z",
|
||||
"app/storefront-development/products/price/examples/show-price/page.mdx": "2025-03-27T14:47:14.292Z",
|
||||
"app/storefront-development/products/price/examples/tax-price/page.mdx": "2025-03-27T14:47:14.292Z",
|
||||
@@ -175,8 +175,8 @@ export const generatedEditDates = {
|
||||
"app/storefront-development/regions/list/page.mdx": "2025-03-27T14:46:52.029Z",
|
||||
"app/storefront-development/regions/store-retrieve-region/page.mdx": "2025-03-27T13:29:54.041Z",
|
||||
"app/storefront-development/regions/page.mdx": "2024-06-09T15:19:09+02:00",
|
||||
"app/storefront-development/tips/page.mdx": "2025-03-26T10:31:43.816Z",
|
||||
"app/storefront-development/page.mdx": "2025-03-27T13:28:22.077Z",
|
||||
"app/storefront-development/tips/page.mdx": "2025-12-09T13:33:33.997Z",
|
||||
"app/storefront-development/page.mdx": "2025-12-09T13:30:25.379Z",
|
||||
"app/troubleshooting/cors-errors/page.mdx": "2024-05-03T17:36:38+03:00",
|
||||
"app/troubleshooting/create-medusa-app-errors/page.mdx": "2025-12-04T14:12:21.480Z",
|
||||
"app/troubleshooting/database-errors/page.mdx": "2025-12-04T14:14:46.745Z",
|
||||
@@ -203,7 +203,7 @@ export const generatedEditDates = {
|
||||
"app/commerce-modules/api-key/_events/page.mdx": "2024-07-03T19:27:13+03:00",
|
||||
"app/commerce-modules/api-key/_events/_events-table/page.mdx": "2024-07-03T19:27:13+03:00",
|
||||
"app/infrastructure-modules/cache/redis/page.mdx": "2025-06-24T08:50:10.115Z",
|
||||
"app/infrastructure-modules/event/redis/page.mdx": "2025-12-04T13:38:38.038Z",
|
||||
"app/infrastructure-modules/event/redis/page.mdx": "2025-12-09T13:29:13.949Z",
|
||||
"app/infrastructure-modules/event/local/page.mdx": "2025-03-27T14:53:13.309Z",
|
||||
"app/infrastructure-modules/workflow-engine/in-memory/page.mdx": "2024-11-19T16:37:47.262Z",
|
||||
"app/infrastructure-modules/cache/in-memory/page.mdx": "2024-11-19T16:37:47.261Z",
|
||||
@@ -937,7 +937,7 @@ export const generatedEditDates = {
|
||||
"references/order/IOrderModuleService/methods/order.IOrderModuleService.updateOrderChangeActions/page.mdx": "2025-10-21T08:10:49.750Z",
|
||||
"references/types/ModulesSdkTypes/types/types.ModulesSdkTypes.RemoteQueryFunction/page.mdx": "2025-10-21T08:10:47.957Z",
|
||||
"references/types/types.CommonTypes/page.mdx": "2025-10-31T09:41:29.372Z",
|
||||
"app/storefront-development/publishable-api-keys/page.mdx": "2025-03-26T10:31:43.815Z",
|
||||
"app/storefront-development/publishable-api-keys/page.mdx": "2025-12-09T13:26:27.641Z",
|
||||
"references/api_key/types/api_key.ExpandScalar/page.mdx": "2024-09-17T00:10:59.563Z",
|
||||
"references/api_key/types/api_key.FilterQuery/page.mdx": "2024-11-27T16:33:40.706Z",
|
||||
"references/api_key/types/api_key.FilterValue/page.mdx": "2024-09-17T00:10:59.571Z",
|
||||
@@ -6227,7 +6227,7 @@ export const generatedEditDates = {
|
||||
"references/events/events.Region/page.mdx": "2025-05-20T07:51:40.897Z",
|
||||
"references/events/events.Sales_Channel/page.mdx": "2025-05-20T07:51:40.897Z",
|
||||
"references/events/events.User/page.mdx": "2025-05-20T07:51:40.897Z",
|
||||
"app/how-to-tutorials/tutorials/saved-payment-methods/page.mdx": "2025-09-11T13:03:49.152Z",
|
||||
"app/how-to-tutorials/tutorials/saved-payment-methods/page.mdx": "2025-12-09T10:56:41.512Z",
|
||||
"references/core_flows/Cart/Workflows_Cart/functions/core_flows.Cart.Workflows_Cart.refundPaymentAndRecreatePaymentSessionWorkflow/page.mdx": "2025-12-03T08:41:35.675Z",
|
||||
"references/core_flows/Cart/Workflows_Cart/variables/core_flows.Cart.Workflows_Cart.refundPaymentAndRecreatePaymentSessionWorkflowId/page.mdx": "2025-05-20T07:51:40.757Z",
|
||||
"references/core_flows/Draft_Order/Workflows_Draft_Order/variables/core_flows.Draft_Order.Workflows_Draft_Order.convertDraftOrderWorkflowId/page.mdx": "2025-05-20T07:51:40.768Z",
|
||||
|
||||
@@ -24,7 +24,7 @@ const generatedgeneratedStorefrontDevelopmentSidebarSidebar = {
|
||||
"isPathHref": true,
|
||||
"type": "link",
|
||||
"path": "/storefront-development/tips",
|
||||
"title": "Tips",
|
||||
"title": "Connect to Medusa",
|
||||
"children": []
|
||||
},
|
||||
{
|
||||
|
||||
@@ -15,7 +15,7 @@ export const storefrontDevelopmentSidebar = [
|
||||
{
|
||||
type: "link",
|
||||
path: "/storefront-development/tips",
|
||||
title: "Tips",
|
||||
title: "Connect to Medusa",
|
||||
},
|
||||
{
|
||||
type: "link",
|
||||
|
||||
Reference in new issue
Block a user