From a6e7d6594e1e09be54c5a4cb782a66eb3a31a7b3 Mon Sep 17 00:00:00 2001
From: Shahed Nasser <shahednasser@gmail.com>
Date: Thu, 14 Nov 2024 17:31:40 +0200
Subject: [PATCH] docs: document nested UI routes

---
 .../admin/ui-routes/page.mdx                  | 34 +++++++++++++++++++
 www/apps/book/generated/edit-dates.mjs        |  2 +-
 2 files changed, 35 insertions(+), 1 deletion(-)

diff --git a/www/apps/book/app/learn/advanced-development/admin/ui-routes/page.mdx b/www/apps/book/app/learn/advanced-development/admin/ui-routes/page.mdx
index a16b7a4971445..890195ef66e88 100644
--- a/www/apps/book/app/learn/advanced-development/admin/ui-routes/page.mdx
+++ b/www/apps/book/app/learn/advanced-development/admin/ui-routes/page.mdx
@@ -99,6 +99,40 @@ The configuration object is created using the `defineRouteConfig` function impor
 
 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).
 
+### Nested UI Routes
+
+Consider that along 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:
+
+```tsx title="src/admin/routes/custom/nested/page.tsx"
+import { defineRouteConfig } from "@medusajs/admin-sdk"
+import { Container, Heading } from "@medusajs/ui"
+
+const NestedCustomPage = () => {
+  return (
+    <Container className="divide-y p-0">
+      <div className="flex items-center justify-between px-6 py-4">
+        <Heading level="h2">This is my nested custom route</Heading>
+      </div>
+    </Container>
+  )
+}
+
+export const config = defineRouteConfig({
+  label: "Nested Route",
+})
+
+export default NestedCustomPage
+```
+
+This UI route is shown in the sidebar as an item nested in the parent "Custom Route" item. Nested items are only shown when the parent sidebar items (in this case, "Custom Route") are clicked.
+
+#### Caveats
+
+Some caveats for nested UI routes in the sidebar:
+
+- Nested dynamic UI routes, such as one created at `src/admin/routes/custom/[id]/page.tsx` aren't added to the sidebar as it's not possible to link to a dynamic route. If the dynamic route exports route configurations, a warning is logged in the browser's console.
+- Nested routes in setting pages aren't shown in the sidebar to follow the admin's design conventions.
+
 ---
 
 ## Create Settings Page
diff --git a/www/apps/book/generated/edit-dates.mjs b/www/apps/book/generated/edit-dates.mjs
index 1b0f767355a7c..e50c3356901c6 100644
--- a/www/apps/book/generated/edit-dates.mjs
+++ b/www/apps/book/generated/edit-dates.mjs
@@ -56,7 +56,7 @@ export const generatedEditDates = {
   "app/learn/advanced-development/api-routes/http-methods/page.mdx": "2024-09-11T10:43:33.169Z",
   "app/learn/advanced-development/admin/tips/page.mdx": "2024-10-07T12:50:36.335Z",
   "app/learn/advanced-development/api-routes/cors/page.mdx": "2024-09-30T08:43:53.121Z",
-  "app/learn/advanced-development/admin/ui-routes/page.mdx": "2024-10-07T12:52:37.509Z",
+  "app/learn/advanced-development/admin/ui-routes/page.mdx": "2024-11-14T15:29:22.901Z",
   "app/learn/advanced-development/api-routes/middlewares/page.mdx": "2024-09-11T10:45:31.861Z",
   "app/learn/advanced-development/modules/isolation/page.mdx": "2024-07-04T17:26:03+03:00",
   "app/learn/advanced-development/data-models/configure-properties/page.mdx": "2024-09-30T08:43:53.122Z",