docs: Document the @/vdb alias for dashboard imports

docs/docs/guides/extending-the-dashboard/getting-started/index.md

@@ -86,7 +86,17 @@ to correctly resolve imports of GraphQL types & interpret JSX in your dashboard
         // highlight-start
         "jsx": "react-jsx",
         "paths": {
-            "@/gql": ["./src/gql/graphql.ts"]
+            "@/gql": [
+                "./src/gql/graphql.ts"
+            ],
+            // This line allows TypeScript to properly resolve internal
+            // Vendure Dashboard imports, which is necessary for
+            // type safety in your dashboard extensions.
+            // This path assumes a root-level tsconfig.json file.
+            // You may need to adjust it if your project structure is different.
+            "@/vdb/*": [
+                "./node_modules/@vendure/dashboard/src/lib/*"
+            ]
         }
         // highlight-end
     },

packages/dashboard/README.md

@@ -1,13 +1,50 @@
 # Vendure Dashboard
 
-This is an admin dashboard for managing Vendure applications. It is designed to supersede the existing Admin UI.
-
-Current status: early work in progress
+This is a React-based admin dashboard for Vendure. It is a standalone application that can be extended to suit the
+needs of any Vendure project.
 
 ## Development
 
 Run `npx vite` to start Vite in dev mode.
 
+### Note on internal `@/vdb` imports
+
+You will notice that the dashboard uses internal Vendure Dashboard imports prefixed with `@/vdb`. This is adapted from the
+convention of Shadcn which uses a `@/*` path alias for internal imports.
+
+**Why not just use relative imports?**
+
+The problem with using relative imports is that they are handled differently by Vite when compiling the dashboard. This
+manifests as things like React Context not working correctly. The underlying reason is that Vite will selectively
+pre-compile source code and mixing the imports between alias and relative can result in 2 "versions" of the same code
+being loaded, which causes issues with React Context and other things that rely on a single instance of a module.
+
+For this reason, try to use the `@/vdb` alias for all internal Vendure Dashboard imports to the "src/lib" directory.
+
+This is especially import for hooks (since many of them use React Context) and there is even a pre-commit hook
+that will run [a script](./scripts/check-internal-imports.js) to ensure that you are not using relative imports for
+internal Vendure Dashboard code.
+
+**Type Safety for Consumers**
+
+Because we ship source code in the npm package, consumers need to tell TypeScript how to resolve these internal
+imports by adding the path alias to _their_ `tsconfig.json` file.
+
+```json
+{
+    "compilerOptions": {
+        "paths": {
+            "@/vdb/*": [
+                "./node_modules/@vendure/dashboard/src/lib/*"
+            ]
+        }
+    }
+}
+```
+
+Note: even without that path alias, the vite compilation will still work, but TypeScript types will not resolve correctly
+when developing dashboard extensions.
+
 ## Testing
 
-Run `npm run test` to run tests once, or `npx vitest` to run tests in watch mode
+Run `npm run test` to run tests once, or `npx vitest` to run tests in watch mode

packages/dashboard/vite/vite-plugin-config.ts

@@ -8,7 +8,7 @@ export function viteConfigPlugin({ packageRoot }: { packageRoot: string }): Plug
             // Only set the vite `root` to the dashboard package when running the dev server.
             // During a production build we still need to reference the dashboard source which
             // lives in `node_modules`, but we don't want the build output to be emitted in there.
-            // Therefore we set `root` only for `serve` and, for `build`, we instead make sure that
+            // Therefore, we set `root` only for `serve` and, for `build`, we instead make sure that
             // an `outDir` **outside** of `node_modules` is used (defaulting to the current working
             // directory if the user did not provide one already).
             config.root = packageRoot;
@@ -37,6 +37,7 @@ export function viteConfigPlugin({ packageRoot }: { packageRoot: string }): Plug
             config.resolve = {
                 alias: {
                     ...(config.resolve?.alias ?? {}),
+                    // See the readme for an explanation of this alias.
                     '@/vdb': path.resolve(packageRoot, './src/lib'),
                     '@/graphql': path.resolve(packageRoot, './src/lib/graphql'),
                 },