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

docs: revise commerce modules overview pages (#10738)

Browse Source 
* revise API Key Module overview

* revise auth module

* support ref sidebar items

* remove examples

* revise cart module

* revise currency

* revise customer module

* revise fulfillment module

* revise inventory module

* revise order module

* revise payment

* revise pricing module

* revise product module

* revise promotion module

* revise region module

* revise sales channel module

* revise stock location module

* revise store module

* revise tax module

* revise user module

* lint content + fix snippets
This commit is contained in:
Shahed Nasser authored and GitHub committed 2024-12-26 10:32:16 +02:00
1 parent c8f9938865
commit ebca8fed28
112 files changed
+9465 -7731
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

www/apps/resources/app/commerce-modules/region/examples/page.mdx
-256
View File
@@ -1,256 +0,0 @@
import { CodeTabs, CodeTab } from "docs-ui"
export const metadata = {
title: `Examples of the Region Module`,
}
# {metadata.title}
In this guide, you’ll find common examples of how you can use the Region Module in your application.
<Note>
You should only use the Region Module's main service when implementing complex customizations. For common cases, check out [available workflows instead](../../../medusa-workflows-reference/page.mdx).
</Note>
## Create a Region
<CodeTabs groupId="app-type">
<CodeTab label="Medusa API Router" value="medusa">
```ts
import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
import { Modules } from "@medusajs/framework/utils"
export async function POST(
req: MedusaRequest,
res: MedusaResponse
): Promise<void> {
const regionModuleService = req.scope.resolve(
Modules.REGION
)
const region = await regionModuleService.createRegions({
name: "Europe",
currency_code: "eur",
})
res.json({
region,
})
}
```
</CodeTab>
<CodeTab label="Next.js App Router" value="nextjs">
```ts
import { NextResponse } from "next/server"
import { initialize as initializeRegionModule } from "@medusajs/medusa/region"
export async function POST(request: Request) {
const regionModuleService = await initializeRegionModule()
const region = await regionModuleService.createRegions({
name: "Europe",
currency_code: "eur",
})
res.json({
region,
})
}
```
</CodeTab>
</CodeTabs>
---
## List Regions
<CodeTabs groupId="app-type">
<CodeTab label="Medusa API Router" value="medusa">
```ts
import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
import { Modules } from "@medusajs/framework/utils"
export async function GET(
req: MedusaRequest,
res: MedusaResponse
): Promise<void> {
const regionModuleService = req.scope.resolve(
Modules.REGION
)
res.json({
regions: await regionModuleService.listRegions(),
})
}
```
</CodeTab>
<CodeTab label="Next.js App Router" value="nextjs">
```ts
import { NextResponse } from "next/server"
import { initialize as initializeRegionModule } from "@medusajs/medusa/region"
export async function GET(request: Request) {
const regionModuleService = await initializeRegionModule()
return NextResponse.json({
regions: await regionModuleService.listRegions(),
})
}
```
</CodeTab>
</CodeTabs>
---
## Retrieve a Region by its ID
<CodeTabs groupId="app-type">
<CodeTab label="Medusa API Router" value="medusa">
```ts
import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
import { Modules } from "@medusajs/framework/utils"
export async function GET(
req: MedusaRequest,
res: MedusaResponse
): Promise<void> {
const regionModuleService = req.scope.resolve(
Modules.REGION
)
const region = await regionModuleService.retrieveRegion("reg_123")
res.json({ region })
}
```
</CodeTab>
<CodeTab label="Next.js App Router" value="nextjs">
```ts
import { NextResponse } from "next/server"
import { initialize as initializeRegionModule } from "@medusajs/medusa/region"
export async function GET(request: Request) {
const regionModuleService = await initializeRegionModule()
const region = await regionModuleService.retrieveRegion("reg_123")
return NextResponse.json({ region })
}
```
</CodeTab>
</CodeTabs>
---
## Update a Region
<CodeTabs groupId="app-type">
<CodeTab label="Medusa API Router" value="medusa">
```ts
import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
import { Modules } from "@medusajs/framework/utils"
export async function POST(
req: MedusaRequest,
res: MedusaResponse
): Promise<void> {
const regionModuleService = req.scope.resolve(
Modules.REGION
)
const region = await regionModuleService.updateRegions("reg_123", {
automatic_taxes: false,
})
res.json({ region })
}
```
</CodeTab>
<CodeTab label="Next.js App Router" value="nextjs">
```ts
import { NextResponse } from "next/server"
import { initialize as initializeRegionModule } from "@medusajs/medusa/region"
export async function POST(request: Request) {
const regionModuleService = await initializeRegionModule()
const region = await regionModuleService.updateRegions("reg_123", {
automatic_taxes: false,
})
return NextResponse.json({ region })
}
```
</CodeTab>
</CodeTabs>
---
## Delete a Region
<CodeTabs groupId="app-type">
<CodeTab label="Medusa API Router" value="medusa">
```ts
import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
import { Modules } from "@medusajs/framework/utils"
export async function DELETE(
req: MedusaRequest,
res: MedusaResponse
): Promise<void> {
const regionModuleService = req.scope.resolve(
Modules.REGION
)
await regionModuleService.deleteRegions("reg_123")
res.status(200)
}
```
</CodeTab>
<CodeTab label="Next.js App Router" value="nextjs">
```ts
import { NextResponse } from "next/server"
import { initialize as initializeRegionModule } from "@medusajs/medusa/region"
export async function DELETE(request: Request) {
const regionModuleService = await initializeRegionModule()
await regionModuleService.deleteRegions("reg_123")
}
```
</CodeTab>
</CodeTabs>
---
## More Examples
The [Region Module's main service reference](/references/region) provides a reference to all the methods available for use with examples for each.
www/apps/resources/app/commerce-modules/region/links-to-other-modules/page.mdx
+12 -12
View File
@@ -39,8 +39,8 @@ To retrieve the carts of a region with [Query](!docs!/learn/fundamentals/module-
const { data: regions } = await query.graph({
entity: "region",
fields: [
"carts.*"
]
"carts.*",
],
})
// regions.carts
@@ -57,8 +57,8 @@ import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
const { data: regions } = useQueryGraphStep({
entity: "region",
fields: [
"carts.*"
]
"carts.*",
],
})
// regions.carts
@@ -84,8 +84,8 @@ To retrieve the orders of a region with [Query](!docs!/learn/fundamentals/module
const { data: regions } = await query.graph({
entity: "region",
fields: [
"orders.*"
]
"orders.*",
],
})
// regions.orders
@@ -102,8 +102,8 @@ import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
const { data: regions } = useQueryGraphStep({
entity: "region",
fields: [
"orders.*"
]
"orders.*",
],
})
// regions.orders
@@ -133,8 +133,8 @@ To retrieve the payment providers of a region with [Query](!docs!/learn/fundamen
const { data: regions } = await query.graph({
entity: "region",
fields: [
"payment_providers.*"
]
"payment_providers.*",
],
})
// regions.payment_providers
@@ -151,8 +151,8 @@ import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
const { data: regions } = useQueryGraphStep({
entity: "region",
fields: [
"payment_providers.*"
]
"payment_providers.*",
],
})
// regions.payment_providers
www/apps/resources/app/commerce-modules/region/page.mdx
+119 -88
View File
@@ -6,125 +6,156 @@ export const metadata = {
# {metadata.title}
The Region Module provides region-related features in your Medusa and Node.js applications.
In this section of the documentation, you will find resources to learn more about the Region Module and how to use it in your application.
Medusa has region related features available out-of-the-box through the Region Module. A [module](!docs!/learn/fundamentals/modules) is a standalone package that provides features for a single domain. Each of Medusa's commerce features are placed in commerce modules, such as this Region Module.
<Note>
Learn more about why modules are isolated in [this documentation](!docs!/learn/fundamentals/modules/isolation).
</Note>
---
## Region Features
- [Region Management](/references/region/models/Region): Manage regions in your store. You can create regions with different currencies and settings.
- [Multi-Currency Support](/references/region/models/Region): Each region has a currency. You can support multiple currencies in your store by creating multiple regions.
- [Different Settings Per Region](/references/region/models/Region): Each region has its own settings, such as what countries belong to a region or its tax settings.
---
## How to Use Region Module's Service
You can use the Region Module's main service by resolving from the Medusa container the resource `Modules.REGION`.
In your Medusa application, you build flows around commerce modules. A flow is built as a [Workflow](!docs!/learn/fundamentals/workflows), which is a special function composed of a series of steps that guarantees data consistency and reliable roll-back mechanism.
You can build custom workflows and steps. You can also re-use Medusa's workflows and steps, which are provided by the `@medusajs/medusa/core-flows` package.
For example:
<CodeTabs groupId="resource-type">
<CodeTab label="Workflow Step" value="workflow-step">
export const highlights = [
["12", "Modules.REGION", "Resolve the module in a step."]
]
```ts title="src/workflows/hello-world/step1.ts"
import { createStep } from "@medusajs/framework/workflows-sdk"
```ts title="src/workflows/create-region.ts" highlights={highlights}
import {
createWorkflow,
WorkflowResponse,
createStep,
StepResponse,
} from "@medusajs/framework/workflows-sdk"
import { Modules } from "@medusajs/framework/utils"
const step1 = createStep("step-1", async (_, { container }) => {
const regionModuleService = container.resolve(
Modules.REGION
)
const createRegionStep = createStep(
"create-region",
async ({}, { container }) => {
const regionModuleService = container.resolve(Modules.REGION)
const regions = await regionModuleService.listRegions()
})
const region = await regionModuleService.createRegions({
name: "Europe",
currency_code: "eur",
})
return new StepResponse({ region }, region.id)
},
async (regionId, { container }) => {
if (!regionId) {
return
}
const regionModuleService = container.resolve(Modules.REGION)
await regionModuleService.deleteRegions([regionId])
}
)
export const createRegionWorkflow = createWorkflow(
"create-region",
() => {
const { region } = createRegionStep()
return new WorkflowResponse({
region,
})
}
)
```
</CodeTab>
<CodeTab label="API Route" value="api-route">
You can then execute the workflow in your custom API routes, scheduled jobs, or subscribers:
```ts title="src/api/store/custom/route.ts"
import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
import { Modules } from "@medusajs/framework/utils"
<CodeTabs group="resource-types">
<CodeTab label="API Route" value="api-route">
```ts title="src/api/workflow/route.ts" highlights={[["11"], ["12"]]} collapsibleLines="1-6" expandButtonLabel="Show Imports"
import type {
MedusaRequest,
MedusaResponse,
} from "@medusajs/framework/http"
import { createRegionWorkflow } from "../../workflows/create-region"
export async function GET(
req: MedusaRequest,
res: MedusaResponse
): Promise<void> {
const regionModuleService = req.scope.resolve(
Modules.REGION
)
) {
const { result } = await createRegionWorkflow(req.scope)
.run()
res.json({
regions: await regionModuleService.listRegions(),
})
res.send(result)
}
```
</CodeTab>
<CodeTab label="Subscriber" value="subscribers">
<CodeTab label="Subscriber" value="subscriber">
```ts title="src/subscribers/user-created.ts" highlights={[["11"], ["12"]]} collapsibleLines="1-6" expandButtonLabel="Show Imports"
import {
type SubscriberConfig,
type SubscriberArgs,
} from "@medusajs/framework"
import { createRegionWorkflow } from "../workflows/create-region"
```ts title="src/subscribers/custom-handler.ts"
import { SubscriberArgs } from "@medusajs/framework"
import { Modules } from "@medusajs/framework/utils"
export default async function handleUserCreated({
event: { data },
container,
}: SubscriberArgs<{ id: string }>) {
const { result } = await createRegionWorkflow(container)
.run()
export default async function subscriberHandler({ container }: SubscriberArgs) {
const regionModuleService = container.resolve(
Modules.REGION
)
console.log(result)
}
const regions = await regionModuleService.listRegions()
export const config: SubscriberConfig = {
event: "user.created",
}
```
</CodeTab>
<CodeTab label="Scheduled Job" value="scheduled-job">
```ts title="src/jobs/run-daily.ts" highlights={[["7"], ["8"]]}
import { MedusaContainer } from "@medusajs/framework/types"
import { createRegionWorkflow } from "../workflows/create-region"
export default async function myCustomJob(
container: MedusaContainer
) {
const { result } = await createRegionWorkflow(container)
.run()
console.log(result)
}
export const config = {
name: "run-once-a-day",
schedule: `0 0 * * *`,
}
```
</CodeTab>
</CodeTabs>
---
## What is a Region?
A region represents the area you sell products in. Each region can cover multiple countries, but uses a single currency.
Learn more about workflows in [this documentation](!docs!/learn/fundamentals/workflows).
---
## Features
### Region Management
You can manage your regions to create, update, retrieve, or delete them.
```ts
const region = await regionModuleService.createRegions({
name: "Europe",
currency_code: "eur",
})
```
### Multi-Currency Support
As each region has a currency, you can support multiple currencies in your store by creating multiple regions.
```ts
const regions = await regionModuleService.createRegions([
{
name: "Europe",
currency_code: "eur",
},
{
name: "United States of America",
currency_code: "usd",
},
])
```
### Different Settings Per Region
Each region has its own settings, such as what countries belong to a region or its tax settings. Each region has different tax rates, payment providers, and more provided by other commerce modules.
```ts
const regions = await regionModuleService.createRegions([
{
name: "Europe",
currency_code: "eur",
countries: ["dk", "de", "fr", "it", "pt"],
automatic_taxes: true,
},
{
name: "United States of America",
currency_code: "usd",
countries: ["us"],
payment_providers: ["stripe"],
},
])
```
<CommerceModuleSections name="Region" />