docs: improvements to admin, query, and read-only link docs (#12239)
* improve admin page * improvemens to query and read-only link docs * fix build error
This commit is contained in:
Shahed Nasser
@@ -4,14 +4,42 @@ export const metadata = {
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
In the next chapters, you'll learn more about possible admin customizations.
|
||||
In this chapter, you'll learn about th Medusa Admin dashboard and the possible ways to customize it.
|
||||
|
||||
You can customize the admin dashboard by:
|
||||
## What is the Medusa Admin?
|
||||
|
||||
- Adding new sections to existing pages using Widgets.
|
||||
- Adding new pages using UI Routes.
|
||||
The Medusa Admin is an intuitive dashboard that allows merchants to manage their ecommerce store. It provides management featuers related to products, orders, customers, and more.
|
||||
|
||||
However, you can't customize the admin dashboard's layout, design, or the content of the existing pages (aside from injecting widgets).
|
||||
<Note title="Tip">
|
||||
|
||||
To explore more what you can do with the Medusa Admin, check out the [User Guide](!user-guide!). These user guides are designed for merchants and provide the steps to perform any task within the Medusa Admin.
|
||||
|
||||
</Note>
|
||||
|
||||
The Medusa Admin is built with [Vite](https://vite.dev/). When you [install the Medusa application](../../installation/page.mdx), you also install the Medusa Admin. Then, when you start the Medusa application, you can access the Medusa Admin at `http://localhost:9000/app`.
|
||||
|
||||
<Note title="Tip">
|
||||
|
||||
If you don't have an admin user, use the [Medusa CLI](!resources!/medusa-cli/commands/user) to create one.
|
||||
|
||||
</Note>
|
||||
|
||||
---
|
||||
|
||||
## How to Customize the Medusa Admin?
|
||||
|
||||
You can customize the Medusa Admin dashboard by:
|
||||
|
||||
- Adding new sections to existing pages using [Widgets](./widgets/page.mdx).
|
||||
- Adding new pages using [UI Routes](./ui-routes/page.mdx).
|
||||
|
||||
The next chapters will cover these two topics in detail.
|
||||
|
||||
### What You Can't Customize in the Medusa Admin
|
||||
|
||||
You can't customize the admin dashboard's layout, design, or the content of the existing pages (aside from injecting widgets).
|
||||
|
||||
If your use case requires heavy customization of the admin dashboard, you can build a custom admin dashboard using Medusa's [Admin API routes](!api!/admin).
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -85,7 +85,7 @@ To test the subscriber, start the Medusa application:
|
||||
npm run dev
|
||||
```
|
||||
|
||||
Then, try placing an order either using Medusa's API routes or the [Next.js Storefront](../../storefront-development/nextjs-starter/page.mdx). You'll see the following message in the terminal:
|
||||
Then, try placing an order either using Medusa's API routes or the [Next.js Storefront](!resources!/nextjs-starter). You'll see the following message in the terminal:
|
||||
|
||||
```bash
|
||||
info: Processing order.placed which has 1 subscribers
|
||||
|
||||
@@ -175,7 +175,7 @@ In the object passed to the `graph` method:
|
||||
- `product.*` to retrieve the fields of a product record linked to a `Post` record.
|
||||
- `post.*` to retrieve the fields of a `Post` record linked to a product record.
|
||||
|
||||
You can then apply any [filters](#apply-filters) or [pagination configurations](#apply-pagination).
|
||||
You can then apply any [filters](#apply-filters) or [pagination configurations](#apply-pagination) on the module link's table. For example, you can apply filters on the `product_id`, `post_id`, and any other custom columns you defined in the link table.
|
||||
|
||||
The returned `data` is similar to the following:
|
||||
|
||||
@@ -238,7 +238,12 @@ Filters don't apply on fields of linked data models from other modules. Refer to
|
||||
|
||||
### Advanced Query Filters
|
||||
|
||||
Under the hood, Query uses the `listX` (`listPosts`) method of the data model's module's service to retrieve records. This method accepts a filter object that can be used to filter records.
|
||||
Under the hood, Query uses one of the following methods from the data model's module's service to retrieve records:
|
||||
|
||||
- `listX` if you don't pass [pagination parameters](#apply-pagination). For example, `listPosts`.
|
||||
- `listAndCountX` if you pass pagination parameters. For example, `listAndCountPosts`.
|
||||
|
||||
Both methods accepts a filter object that can be used to filter records.
|
||||
|
||||
Those filters don't just allow you to filter by exact values. You can also filter by properties that don't match a value, match multiple values, and other filter types.
|
||||
|
||||
|
||||
@@ -381,6 +381,7 @@ Read-only module links are most useful when working with data models that aren't
|
||||
To define the read-only module link to a virtual data model, you must:
|
||||
|
||||
1. Create a `list` method in the custom module's service. This method retrieves the linked records filtered by the ID(s) of the first data model.
|
||||
- You can also create a `listAndCount` method to retrieve the related records with pagination.
|
||||
2. Define the read-only module link from the first data model to the virtual data model.
|
||||
3. Use Query to retrieve the first data model and its linked records from the virtual data model.
|
||||
|
||||
@@ -395,6 +396,8 @@ Refer to the [Modules chapter](../../modules/page.mdx) to learn how to create a
|
||||
</Note>
|
||||
|
||||
```ts title="src/modules/cms/service.ts"
|
||||
import { FindConfig } from "@medusajs/framework/types"
|
||||
|
||||
type CmsModuleOptions = {
|
||||
apiKey: string
|
||||
}
|
||||
@@ -427,6 +430,36 @@ export default class CmsModuleService {
|
||||
* ]
|
||||
*/
|
||||
}
|
||||
|
||||
// To retrieve with pagination
|
||||
async listAndCount(
|
||||
filter: {
|
||||
id: string | string[]
|
||||
},
|
||||
config?: FindConfig<any> | undefined,
|
||||
) {
|
||||
return this.client.getPosts(filter, {
|
||||
limit: config?.take,
|
||||
offset: config?.skip,
|
||||
})
|
||||
/**
|
||||
* Example of returned data:
|
||||
*
|
||||
* {
|
||||
* count: 2,
|
||||
* data: [
|
||||
* {
|
||||
* "id": "post_123",
|
||||
* "product_id": "prod_321"
|
||||
* },
|
||||
* {
|
||||
* "id": "post_456",
|
||||
* "product_id": "prod_654"
|
||||
* }
|
||||
* ]
|
||||
* }
|
||||
*/
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
@@ -434,6 +467,8 @@ The above service initializes a client, assuming your CMS has an SDK that allows
|
||||
|
||||
The service must have a `list` method to be part of the read-only module link. This method accepts the ID(s) of the products to retrieve their associated posts. The posts must include the product's ID in a field, such as `product_id`.
|
||||
|
||||
You can also create a `listAndCount` method to retrieve the posts with pagination. This method is called if you pass [pagination parameters to Query](../query/page.mdx#apply-pagination).
|
||||
|
||||
Next, define a read-only module link from the Product Module to the CMS Module:
|
||||
|
||||
```ts title="src/links/product-cms.ts"
|
||||
|
||||
@@ -10,7 +10,7 @@ In this chapter, you'll learn how to install and run a Medusa application.
|
||||
|
||||
## Create Medusa Application
|
||||
|
||||
A Medusa application is made up of a Node.js server and an admin dashboard. You can optionally install a separate [Next.js storefront](../storefront-development/nextjs-starter/page.mdx) either while installing the Medusa application or at a later point.
|
||||
A Medusa application is made up of a Node.js server and an admin dashboard. You can optionally install a separate [Next.js storefront](!resources!/nextjs-starter) either while installing the Medusa application or at a later point.
|
||||
|
||||
<Prerequisites items={[
|
||||
{
|
||||
@@ -81,7 +81,7 @@ This runs your Medusa application at `http://localhost:9000`, and the Medusa Adm
|
||||
|
||||
<Note title="Tip">
|
||||
|
||||
For details on starting and configuring the Next.js storefront, refer to [this documentation](../storefront-development/nextjs-starter/page.mdx).
|
||||
For details on starting and configuring the Next.js storefront, refer to [this documentation](!resources!/nextjs-starter).
|
||||
|
||||
</Note>
|
||||
|
||||
|
||||
@@ -1,83 +0,0 @@
|
||||
import { Prerequisites } from "docs-ui"
|
||||
|
||||
export const metadata = {
|
||||
title: `${pageNumber} Next.js Starter Storefront`,
|
||||
}
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
The Medusa application is made up of a Node.js server and an admin dashboard. The storefront is installed and hosted separately from the Medusa application, giving you the flexibility to choose the frontend tech stack that you and your team are proficient in, and implement unique design systems and user experience.
|
||||
|
||||
The Next.js Starter storefront provides rich commerce features and a sleek design. Developers and businesses can use it as-is or build on top of it to tailor it for the business's unique use case, design, and customer experience.
|
||||
|
||||
In this chapter, you’ll learn how to install the Next.js Starter storefront separately from the Medusa application. You can also install it while installing the Medusa application as explained in [the installation chapter](../../installation/page.mdx).
|
||||
|
||||
## Install Next.js Starter
|
||||
|
||||
<Prerequisites items={[
|
||||
{
|
||||
text: "Node.js v20+",
|
||||
link: "https://nodejs.org/en/download"
|
||||
},
|
||||
{
|
||||
text: "Git CLI tool",
|
||||
link: "https://git-scm.com/downloads"
|
||||
},
|
||||
{
|
||||
text: "At least one region in the Medusa application.",
|
||||
},
|
||||
]} />
|
||||
|
||||
If you already have a Medusa application installed with at least one region, you can install the Next.js Starter storefront with the following steps:
|
||||
|
||||
1. Clone the [Next.js Starter](https://github.com/medusajs/nextjs-starter-medusa):
|
||||
|
||||
```bash
|
||||
git clone https://github.com/medusajs/nextjs-starter-medusa my-medusa-storefront
|
||||
```
|
||||
|
||||
2. Change to the `my-medusa-storefront` directory, install the dependencies, and rename the template environment variable file:
|
||||
|
||||
```bash npm2yarn
|
||||
cd my-medusa-storefront
|
||||
npm install
|
||||
mv .env.template .env.local
|
||||
```
|
||||
|
||||
3. Set the Medusa application's publishable API key in the `NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY` environment variable. You can retrieve the publishable API key in on the Medusa Admin dashboard by going to Settings -> Publishable API Keys
|
||||
|
||||
```bash
|
||||
NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY=pk_123...
|
||||
```
|
||||
|
||||
4. While the Medusa application is running, start the Next.js Starter storefront:
|
||||
|
||||
```bash npm2yarn
|
||||
npm run dev
|
||||
```
|
||||
|
||||
Your Next.js Starter storefront is now running at `http://localhost:8000`.
|
||||
|
||||
---
|
||||
|
||||
## Customize Storefront
|
||||
|
||||
To customize the storefront, refer to the following directories:
|
||||
|
||||
- `src/app`: The storefront’s pages.
|
||||
- `src/modules`: The storefront’s components.
|
||||
- `src/styles`: The storefront’s styles.
|
||||
|
||||
<Note title="Tip">
|
||||
|
||||
You can learn more about development with Next.js through [their documentation](https://nextjs.org/docs/getting-started).
|
||||
|
||||
</Note>
|
||||
|
||||
---
|
||||
|
||||
## Configurations and Integrations
|
||||
|
||||
The Next.js Starter is compatible with some Medusa integrations out-of-the-box, such as the Stripe provider module. You can also change some of its configurations if necessary.
|
||||
|
||||
Refer to the [Next.js Starter reference](!resources!/nextjs-starter) for more details.
|
||||
@@ -8,7 +8,6 @@ export const generatedEditDates = {
|
||||
"app/learn/fundamentals/workflows/workflow-hooks/page.mdx": "2024-12-09T10:44:33.781Z",
|
||||
"app/learn/debugging-and-testing/logging/page.mdx": "2024-09-30T08:43:53.135Z",
|
||||
"app/learn/storefront-development/page.mdx": "2024-12-10T09:11:04.993Z",
|
||||
"app/learn/storefront-development/nextjs-starter/page.mdx": "2024-12-10T09:05:18.960Z",
|
||||
"app/learn/fundamentals/page.mdx": "2024-07-04T17:26:03+03:00",
|
||||
"app/learn/fundamentals/admin-customizations/page.mdx": "2024-10-07T12:41:39.218Z",
|
||||
"app/learn/fundamentals/workflows/workflow-timeout/page.mdx": "2024-10-21T13:30:21.372Z",
|
||||
@@ -17,7 +16,7 @@ export const generatedEditDates = {
|
||||
"app/learn/fundamentals/api-routes/page.mdx": "2024-12-04T11:02:57.134Z",
|
||||
"app/learn/fundamentals/modules/modules-directory-structure/page.mdx": "2024-12-09T10:32:46.839Z",
|
||||
"app/learn/fundamentals/workflows/access-workflow-errors/page.mdx": "2024-10-21T13:30:21.371Z",
|
||||
"app/learn/fundamentals/events-and-subscribers/page.mdx": "2025-04-17T08:29:09.896Z",
|
||||
"app/learn/fundamentals/events-and-subscribers/page.mdx": "2025-04-18T10:42:32.803Z",
|
||||
"app/learn/fundamentals/modules/container/page.mdx": "2025-03-18T15:10:03.574Z",
|
||||
"app/learn/fundamentals/workflows/execute-another-workflow/page.mdx": "2024-12-09T15:56:22.895Z",
|
||||
"app/learn/fundamentals/modules/loaders/page.mdx": "2025-03-24T06:40:39.948Z",
|
||||
@@ -31,7 +30,7 @@ export const generatedEditDates = {
|
||||
"app/learn/fundamentals/events-and-subscribers/emit-event/page.mdx": "2025-03-18T15:09:40.243Z",
|
||||
"app/learn/fundamentals/workflows/conditions/page.mdx": "2025-01-27T08:45:19.027Z",
|
||||
"app/learn/fundamentals/modules/module-link-directions/page.mdx": "2024-07-24T09:16:01+02:00",
|
||||
"app/learn/fundamentals/admin/page.mdx": "2025-03-21T08:25:13.754Z",
|
||||
"app/learn/fundamentals/admin/page.mdx": "2025-04-18T10:28:47.328Z",
|
||||
"app/learn/fundamentals/workflows/long-running-workflow/page.mdx": "2025-03-28T07:02:34.467Z",
|
||||
"app/learn/fundamentals/workflows/constructor-constraints/page.mdx": "2025-02-12T13:55:33.437Z",
|
||||
"app/learn/fundamentals/data-models/write-migration/page.mdx": "2025-03-24T06:41:48.915Z",
|
||||
@@ -68,7 +67,7 @@ export const generatedEditDates = {
|
||||
"app/learn/fundamentals/module-links/custom-columns/page.mdx": "2025-03-11T13:29:54.752Z",
|
||||
"app/learn/fundamentals/module-links/directions/page.mdx": "2025-03-17T12:52:06.161Z",
|
||||
"app/learn/fundamentals/module-links/page.mdx": "2025-04-17T08:50:17.036Z",
|
||||
"app/learn/fundamentals/module-links/query/page.mdx": "2025-04-17T08:50:17.036Z",
|
||||
"app/learn/fundamentals/module-links/query/page.mdx": "2025-04-18T11:13:02.240Z",
|
||||
"app/learn/fundamentals/modules/db-operations/page.mdx": "2025-03-21T09:21:46.901Z",
|
||||
"app/learn/fundamentals/modules/multiple-services/page.mdx": "2025-03-18T15:11:44.632Z",
|
||||
"app/learn/fundamentals/modules/page.mdx": "2025-03-18T07:51:09.049Z",
|
||||
@@ -99,7 +98,7 @@ export const generatedEditDates = {
|
||||
"app/learn/build/page.mdx": "2024-12-09T11:05:17.383Z",
|
||||
"app/learn/deployment/general/page.mdx": "2025-04-17T08:29:09.878Z",
|
||||
"app/learn/fundamentals/workflows/multiple-step-usage/page.mdx": "2024-11-25T16:19:32.169Z",
|
||||
"app/learn/installation/page.mdx": "2025-03-11T08:55:12.967Z",
|
||||
"app/learn/installation/page.mdx": "2025-04-18T10:42:42.598Z",
|
||||
"app/learn/fundamentals/data-models/check-constraints/page.mdx": "2024-12-06T14:34:50.384Z",
|
||||
"app/learn/fundamentals/module-links/link/page.mdx": "2025-04-07T08:03:14.513Z",
|
||||
"app/learn/fundamentals/workflows/store-executions/page.mdx": "2025-04-17T08:29:10.166Z",
|
||||
@@ -117,7 +116,7 @@ export const generatedEditDates = {
|
||||
"app/learn/configurations/medusa-config/page.mdx": "2025-04-17T08:29:09.907Z",
|
||||
"app/learn/configurations/ts-aliases/page.mdx": "2025-02-11T16:57:46.683Z",
|
||||
"app/learn/production/worker-mode/page.mdx": "2025-03-11T15:21:50.906Z",
|
||||
"app/learn/fundamentals/module-links/read-only/page.mdx": "2025-03-21T09:14:54.944Z",
|
||||
"app/learn/fundamentals/module-links/read-only/page.mdx": "2025-04-18T11:09:13.328Z",
|
||||
"app/learn/fundamentals/data-models/properties/page.mdx": "2025-03-18T07:57:17.826Z",
|
||||
"app/learn/fundamentals/framework/page.mdx": "2025-04-17T16:07:19.090Z",
|
||||
"app/learn/fundamentals/api-routes/retrieve-custom-links/page.mdx": "2025-04-18T07:38:56.729Z"
|
||||
|
||||
+17117
-17123
File diff suppressed because it is too large
Load Diff
@@ -812,7 +812,7 @@ This subscriber now runs whenever an order is placed. You'll see this in action
|
||||
|
||||
## Test it Out: Place an Order
|
||||
|
||||
To test out the Resend integration, you'll place an order using the [Next.js storefront](!docs!/learn/storefront-development/nextjs-starter) that you installed as part of installing Medusa.
|
||||
To test out the Resend integration, you'll place an order using the [Next.js storefront](../../../nextjs-starter/page.mdx) that you installed as part of installing Medusa.
|
||||
|
||||
Start your Medusa application first:
|
||||
|
||||
|
||||
Reference in New Issue
Block a user