Skip to content

Commit 7652329

Browse files
bqstshahednasser
bqst
and
shahednasser
authored
docs: add custom admin route ranking documentation (medusajs#13984)
## Summary **What** — What changes are introduced in this PR? Related PR medusajs#13946 Add custom admin route ranking documentation **Why** — Why are these changes relevant or necessary? *Please provide answer here* **How** — How have these changes been implemented? *Please provide answer here* **Testing** — How have these changes been tested, or how can the reviewer test the feature? *Please provide answer here* --- ## Examples Provide examples or code snippets that demonstrate how this feature works, or how it can be used in practice. This helps with documentation and ensures maintainers can quickly understand and verify the change. ```ts // Example usage ``` --- ## Checklist Please ensure the following before requesting a review: - [ ] I have added a **changeset** for this PR - Every non-breaking change should be marked as a **patch** - To add a changeset, run `yarn changeset` and follow the prompts - [ ] The changes are covered by relevant **tests** - [ ] I have verified the code works as intended locally - [ ] I have linked the related issue(s) if applicable --- ## Additional Context Add any additional context, related issues, or references that might help the reviewer understand this PR. --- > [!NOTE] > Adds admin UI docs for sidebar route ranking (including nested), sorting rules, and examples using CodeTabs; mirrors updates in the public content file. > > - **Docs (Admin UI Routes)** in `www/apps/book/app/learn/fundamentals/admin/ui-routes/page.mdx`: > - Add `rank` property to `defineRouteConfig` docs and explain sidebar ordering. > - New section: "Specify UI Route Sidebar Rank" with version note (v2.11.4). > - Add sorting rules for ranked vs. unranked routes. > - Add "Nested UI Routes Ranking" with examples under `orders`. > - Provide two example routes (Analytics, Reports) demonstrating rank via `CodeTabs`/`CodeTab` (and import them). > - Minor copy tweaks (e.g., possessive fix in `label` description). > - **Public content mirror** in `www/apps/book/public/llms-full.txt`: > - Sync the above additions: `rank` property, ranking section, sorting rules, nested ranking examples, and copy fixes. > > <sup>Written by [Cursor Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit 1d127af. This will update automatically on new commits. Configure [here](https://cursor.com/dashboard?tab=bugbot).</sup> Co-authored-by: Shahed Nasser <[email protected]>
1 parent fc2ac37 commit 7652329

File tree

2 files changed

+208
-3
lines changed

2 files changed

+208
-3
lines changed

‎www/apps/book/app/learn/fundamentals/admin/ui-routes/page.mdx‎

Lines changed: 109 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
import { Prerequisites } from "docs-ui"
1+
import { Prerequisites, CodeTab, CodeTabs } from "docs-ui"
22

33
export const metadata = {
44
title: `${pageNumber} Admin UI Routes`,
@@ -105,11 +105,94 @@ export default CustomPage
105105

106106
The configuration object is created using `defineRouteConfig` from the Medusa Framework. It accepts the following properties:
107107

108-
- `label`: the sidebar item’s label.
108+
- `label`: the sidebar item's label.
109109
- `icon`: an optional React component used as an icon in the sidebar.
110+
- `rank`: an optional number to order the route among sibling routes. Learn more in the [Specify UI Route Sidebar Rank](#specify-ui-route-sidebar-rank) section.
110111

111112
The above example adds a new sidebar item with the label `Custom Route` and an icon from the [Medusa UI Icons package](!ui!/icons/overview).
112113

114+
### Specify UI Route Sidebar Rank
115+
116+
<Note>
117+
118+
UI route ranking is available starting [Medusa v2.11.4](https://github.com/medusajs/medusa/releases/tag/v2.11.4).
119+
120+
</Note>
121+
122+
By default, custom UI routes are added to the sidebar in the order their files are loaded. This applies to your custom UI routes, and UI routes defined in plugins.
123+
124+
You can specify the ranking of your UI route in the sidebar using the `rank` property passed to `defineRouteConfig`.
125+
126+
For example, consider you have the following UI routes:
127+
128+
<CodeTabs group="ui-routes">
129+
<CodeTab label="UI Route 1" value="ui-route-1">
130+
131+
```tsx title="src/admin/routes/analytics/page.tsx" highlights={[["18"]]}
132+
import { defineRouteConfig } from "@medusajs/admin-sdk"
133+
import { ChartBar } from "@medusajs/icons"
134+
import { Container, Heading } from "@medusajs/ui"
135+
136+
const AnalyticsPage = () => {
137+
return (
138+
<Container className="divide-y p-0">
139+
<div className="flex items-center justify-between px-6 py-4">
140+
<Heading level="h2">Analytics Dashboard</Heading>
141+
</div>
142+
</Container>
143+
)
144+
}
145+
146+
export const config = defineRouteConfig({
147+
label: "Analytics",
148+
icon: ChartBar,
149+
rank: 1,
150+
})
151+
152+
export default AnalyticsPage
153+
```
154+
155+
</CodeTab>
156+
<CodeTab label="UI Route 2" value="ui-route-2">
157+
158+
```tsx title="src/admin/routes/reports/page.tsx" highlights={[["18"]]}
159+
import { defineRouteConfig } from "@medusajs/admin-sdk"
160+
import { DocumentText } from "@medusajs/icons"
161+
import { Container, Heading } from "@medusajs/ui"
162+
163+
const ReportsPage = () => {
164+
return (
165+
<Container className="divide-y p-0">
166+
<div className="flex items-center justify-between px-6 py-4">
167+
<Heading level="h2">Reports</Heading>
168+
</div>
169+
</Container>
170+
)
171+
}
172+
173+
export const config = defineRouteConfig({
174+
label: "Reports",
175+
icon: DocumentText,
176+
rank: 2,
177+
})
178+
179+
export default ReportsPage
180+
```
181+
182+
</CodeTab>
183+
</CodeTabs>
184+
185+
In the sidebar, "Analytics" with the rank `1` will be added before "Reports" with the rank `2`.
186+
187+
#### How are UI Routes Sorted in the Sidebar
188+
189+
Medusa sorts custom UI routes based on their rank:
190+
191+
1. UI routes that have ranks are sorted in ascending order.
192+
2. UI routes without a rank are added after the ranked UI routes.
193+
194+
Medusa also applies the same sorting logic to UI routes at the nested level. Learn more in the [Nested UI Routes Ranking](#nested-ui-routes-ranking) section.
195+
113196
### Nested UI Routes
114197

115198
Consider that alongside the UI route above at `src/admin/routes/custom/page.tsx` you create a nested UI route at `src/admin/routes/custom/nested/page.tsx` that also exports route configurations:
@@ -175,6 +258,30 @@ export default NestedOrdersPage
175258

176259
The `nested` property passed to `defineRouteConfig` specifies which route this custom route is nested under. This route will now show in the sidebar under the existing "Orders" sidebar item.
177260

261+
#### Nested UI Routes Ranking
262+
263+
Nested UI routes also accept the [rank](#specify-ui-route-sidebar-rank) configuration. It allows you to specify the order that the nested UI routes are shown in the sidebar under the parent item.
264+
265+
For example:
266+
267+
```tsx title="src/admin/routes/orders/insights/page.tsx"
268+
// In nested UI route 1 at src/admin/routes/orders/insights/page.tsx
269+
export const config = defineRouteConfig({
270+
label: "Order Insights",
271+
nested: "/orders",
272+
rank: 1, // Will appear first
273+
})
274+
275+
// In nested UI route 2 at src/admin/routes/orders/reports/page.tsx
276+
export const config = defineRouteConfig({
277+
label: "Order Reports",
278+
nested: "/orders",
279+
rank: 2, // Will appear second
280+
})
281+
```
282+
283+
In this example, the "Order Insights" item will appear before the "Order Reports" item under the parent "Orders" item in the sidebar.
284+
178285
---
179286

180287
## Create Settings Page

‎www/apps/book/public/llms-full.txt‎

Lines changed: 99 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9365,11 +9365,85 @@ export default CustomPage
93659365

93669366
The configuration object is created using `defineRouteConfig` from the Medusa Framework. It accepts the following properties:
93679367

9368-
- `label`: the sidebar item’s label.
9368+
- `label`: the sidebar item's label.
93699369
- `icon`: an optional React component used as an icon in the sidebar.
9370+
- `rank`: an optional number to order the route among sibling routes. Learn more in the [Specify UI Route Sidebar Rank](#specify-ui-route-sidebar-rank) section.
93709371

93719372
The above example adds a new sidebar item with the label `Custom Route` and an icon from the [Medusa UI Icons package](https://docs.medusajs.com/ui/icons/overview/index.html.md).
93729373

9374+
### Specify UI Route Sidebar Rank
9375+
9376+
UI route ranking is available starting [Medusa v2.11.4](https://github.com/medusajs/medusa/releases/tag/v2.11.4).
9377+
9378+
By default, custom UI routes are added to the sidebar in the order their files are loaded. This applies to your custom UI routes, and UI routes defined in plugins.
9379+
9380+
You can specify the ranking of your UI route in the sidebar using the `rank` property passed to `defineRouteConfig`.
9381+
9382+
For example, consider you have the following UI routes:
9383+
9384+
### UI Route 1
9385+
9386+
```tsx title="src/admin/routes/analytics/page.tsx" highlights={[["18"]]}
9387+
import { defineRouteConfig } from "@medusajs/admin-sdk"
9388+
import { ChartBar } from "@medusajs/icons"
9389+
import { Container, Heading } from "@medusajs/ui"
9390+
9391+
const AnalyticsPage = () => {
9392+
return (
9393+
<Container className="divide-y p-0">
9394+
<div className="flex items-center justify-between px-6 py-4">
9395+
<Heading level="h2">Analytics Dashboard</Heading>
9396+
</div>
9397+
</Container>
9398+
)
9399+
}
9400+
9401+
export const config = defineRouteConfig({
9402+
label: "Analytics",
9403+
icon: ChartBar,
9404+
rank: 1,
9405+
})
9406+
9407+
export default AnalyticsPage
9408+
```
9409+
9410+
### UI Route 2
9411+
9412+
```tsx title="src/admin/routes/reports/page.tsx" highlights={[["18"]]}
9413+
import { defineRouteConfig } from "@medusajs/admin-sdk"
9414+
import { DocumentText } from "@medusajs/icons"
9415+
import { Container, Heading } from "@medusajs/ui"
9416+
9417+
const ReportsPage = () => {
9418+
return (
9419+
<Container className="divide-y p-0">
9420+
<div className="flex items-center justify-between px-6 py-4">
9421+
<Heading level="h2">Reports</Heading>
9422+
</div>
9423+
</Container>
9424+
)
9425+
}
9426+
9427+
export const config = defineRouteConfig({
9428+
label: "Reports",
9429+
icon: DocumentText,
9430+
rank: 2,
9431+
})
9432+
9433+
export default ReportsPage
9434+
```
9435+
9436+
In the sidebar, "Analytics" with the rank `1` will be added before "Reports" with the rank `2`.
9437+
9438+
#### How are UI Routes Sorted in the Sidebar
9439+
9440+
Medusa sorts custom UI routes based on their rank:
9441+
9442+
1. UI routes that have ranks are sorted in ascending order.
9443+
2. UI routes without a rank are added after the ranked UI routes.
9444+
9445+
Medusa also applies the same sorting logic to UI routes at the nested level. Learn more in the [Nested UI Routes Ranking](#nested-ui-routes-ranking) section.
9446+
93739447
### Nested UI Routes
93749448

93759449
Consider that alongside the UI route above at `src/admin/routes/custom/page.tsx` you create a nested UI route at `src/admin/routes/custom/nested/page.tsx` that also exports route configurations:
@@ -9435,6 +9509,30 @@ export default NestedOrdersPage
94359509

94369510
The `nested` property passed to `defineRouteConfig` specifies which route this custom route is nested under. This route will now show in the sidebar under the existing "Orders" sidebar item.
94379511

9512+
#### Nested UI Routes Ranking
9513+
9514+
Nested UI routes also accept the [rank](#specify-ui-route-sidebar-rank) configuration. It allows you to specify the order that the nested UI routes are shown in the sidebar under the parent item.
9515+
9516+
For example:
9517+
9518+
```tsx title="src/admin/routes/orders/insights/page.tsx"
9519+
// In nested UI route 1 at src/admin/routes/orders/insights/page.tsx
9520+
export const config = defineRouteConfig({
9521+
label: "Order Insights",
9522+
nested: "/orders",
9523+
rank: 1, // Will appear first
9524+
})
9525+
9526+
// In nested UI route 2 at src/admin/routes/orders/reports/page.tsx
9527+
export const config = defineRouteConfig({
9528+
label: "Order Reports",
9529+
nested: "/orders",
9530+
rank: 2, // Will appear second
9531+
})
9532+
```
9533+
9534+
In this example, the "Order Insights" item will appear before the "Order Reports" item under the parent "Orders" item in the sidebar.
9535+
94389536
***
94399537

94409538
## Create Settings Page

0 commit comments

Comments
 (0)