docs: add a troubleshooting guide for dist imports (medusajs#9442)

vennyx-org · Oct 7, 2024 · b8896ff · b8896ff
1 parent 789baa0
commit b8896ff
Show file tree

Hide file tree

Showing 6 changed files with 55 additions and 30 deletions.
diff --git a/www/apps/resources/app/troubleshooting/dist-imports/page.mdx b/www/apps/resources/app/troubleshooting/dist-imports/page.mdx
@@ -0,0 +1,36 @@
+export const metadata = {
+  title: `Importing from /dist Sub-Path`,
+}
+
+# {metadata.title}
+
+Because of how Medusa packages are bundled and released, importing from the `/dist` sub-path of its packages is not allowed.
+
+For example, this is not allowed:
+
+```ts
+import { 
+  AdminGetApiKeysParams
+} from "@medusajs/medusa/dist/api/admin/api-keys" // <-- Not allowed
+```
+
+## Importing from Exposed Directories
+
+The `@medusajs/medusa` package allows you to import from the following sub-directories:
+
+- `api`
+- `subscribers`
+- `jobs`
+- `core-flows`
+- `loaders`
+- `commands`
+
+So, you can still import `AdminGetApiKeysParams` from the example above, however, the import path shouldn't include `/dist`.
+
+So, this is allowed:
+
+```ts
+import { 
+  AdminGetApiKeysParams
+} from "@medusajs/medusa/api/admin/api-keys" // <-- Allowed
+```
diff --git a/www/apps/resources/app/troubleshooting/pnpm-errors/page.mdx b/www/apps/resources/app/troubleshooting/pnpm-errors/page.mdx
diff --git a/www/apps/resources/generated/edit-dates.mjs b/www/apps/resources/generated/edit-dates.mjs
@@ -216,7 +216,6 @@ export const generatedEditDates = {
   "app/troubleshooting/errors-after-upgrading/page.mdx": "2024-07-11T10:29:13+03:00",
   "app/troubleshooting/errors-installing-cli/page.mdx": "2024-05-03T17:36:38+03:00",
   "app/troubleshooting/general-errors/page.mdx": "2024-05-03T17:36:38+03:00",
-  "app/troubleshooting/pnpm-errors/page.mdx": "2024-08-13T09:54:56+03:00",
   "app/troubleshooting/s3/page.mdx": "2024-08-06T09:59:46+03:00",
   "app/troubleshooting/page.mdx": "2024-07-18T08:57:11+02:00",
   "app/upgrade-guides/page.mdx": "2024-07-18T08:57:11+02:00",
@@ -2223,5 +2222,6 @@ export const generatedEditDates = {
   "references/types/types/types.AdminBaseReturnReasonPayload/page.mdx": "2024-10-03T00:11:53.303Z",
   "references/user/IMessageAggregator/methods/user.IMessageAggregator.getMessages/page.mdx": "2024-10-03T00:12:20.668Z",
   "references/user/interfaces/user.IModuleService/page.mdx": "2024-10-03T00:12:20.657Z",
-  "references/user/interfaces/user.MessageAggregatorFormat/page.mdx": "2024-10-03T00:12:20.662Z"
+  "references/user/interfaces/user.MessageAggregatorFormat/page.mdx": "2024-10-03T00:12:20.662Z",
+  "app/troubleshooting/dist-imports/page.mdx": "2024-10-03T09:19:37.639Z"
 }
diff --git a/www/apps/resources/generated/files-map.mjs b/www/apps/resources/generated/files-map.mjs
@@ -911,6 +911,10 @@ export const filesMap = [
     "filePath": "/www/apps/resources/app/troubleshooting/deployment/page.mdx",
     "pathname": "/troubleshooting/deployment"
   },
+  {
+    "filePath": "/www/apps/resources/app/troubleshooting/dist-imports/page.mdx",
+    "pathname": "/troubleshooting/dist-imports"
+  },
   {
     "filePath": "/www/apps/resources/app/troubleshooting/eaddrinuse/page.mdx",
     "pathname": "/troubleshooting/eaddrinuse"
@@ -935,10 +939,6 @@ export const filesMap = [
     "filePath": "/www/apps/resources/app/troubleshooting/page.mdx",
     "pathname": "/troubleshooting"
   },
-  {
-    "filePath": "/www/apps/resources/app/troubleshooting/pnpm-errors/page.mdx",
-    "pathname": "/troubleshooting/pnpm-errors"
-  },
   {
     "filePath": "/www/apps/resources/app/troubleshooting/s3/page.mdx",
     "pathname": "/troubleshooting/s3"

diff --git a/www/apps/resources/generated/sidebar.mjs b/www/apps/resources/generated/sidebar.mjs
@@ -8631,14 +8631,6 @@ export const generatedSidebar = [
                 "title": "Errors Installing CLI",
                 "children": []
               },
-              {
-                "loaded": true,
-                "isPathHref": true,
-                "type": "link",
-                "path": "/troubleshooting/pnpm-errors",
-                "title": "pnpm Errors",
-                "children": []
-              },
               {
                 "loaded": true,
                 "isPathHref": true,
@@ -8670,6 +8662,14 @@ export const generatedSidebar = [
                 "path": "/troubleshooting/database-errors",
                 "title": "Database Errors",
                 "children": []
+              },
+              {
+                "loaded": true,
+                "isPathHref": true,
+                "type": "link",
+                "path": "/troubleshooting/dist-imports",
+                "title": "Importing from /dist",
+                "children": []
               }
             ]
           },

diff --git a/www/apps/resources/sidebar.mjs b/www/apps/resources/sidebar.mjs
@@ -2123,11 +2123,6 @@ export const sidebar = sidebarAttachHrefCommonOptions([
                 path: "/troubleshooting/errors-installing-cli",
                 title: "Errors Installing CLI",
               },
-              {
-                type: "link",
-                path: "/troubleshooting/pnpm-errors",
-                title: "pnpm Errors",
-              },
               {
                 type: "link",
                 path: "/troubleshooting/general-errors",
@@ -2149,6 +2144,11 @@ export const sidebar = sidebarAttachHrefCommonOptions([
                 path: "/troubleshooting/database-errors",
                 title: "Database Errors",
               },
+              {
+                type: "link",
+                path: "/troubleshooting/dist-imports",
+                title: "Importing from /dist"
+              }
             ],
           },
           {