@vendure/docs 0.0.0-202601161541

package/docs/guides/extending-the-dashboard/extending-overview/index.md

@@ -0,0 +1,228 @@
+---
+title: 'Extending the Dashboard'
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+The custom functionality you create in your Vendure plugins often needs to be exposed via the Dashboard so that
+administrators can interact with it.
+
+This guide covers how you can set up your plugins with extensions to the Dashboard.
+
+## Plugin Setup
+
+For the purposes of the guides in this section of the docs, we will work with a simple Content Management System (CMS)
+plugin that allows us to create and manage content articles.
+
+Let's create the plugin:
+
+```bash
+npx vendure add --plugin cms
+```
+
+Now let's add an entity to the plugin:
+
+```bash
+npx vendure add --entity Article --selected-plugin CmsPlugin --custom-fields
+```
+
+You now have your `CmsPlugin` created with a new `Article` entity. You can find the plugin in the `./src/plugins/cms` directory.
+
+Let's edit the entity to add the appropriate fields:
+
+```ts title="src/plugins/cms/entities/article.entity.ts"
+import { DeepPartial, HasCustomFields, VendureEntity } from '@vendure/core';
+import { Column, Entity } from 'typeorm';
+
+export class ArticleCustomFields {}
+
+@Entity()
+export class Article extends VendureEntity implements HasCustomFields {
+    constructor(input?: DeepPartial<Article>) {
+        super(input);
+    }
+
+    @Column()
+    slug: string;
+
+    @Column()
+    title: string;
+
+    @Column('text')
+    body: string;
+
+    @Column()
+    isPublished: boolean;
+
+    @Column(type => ArticleCustomFields)
+    customFields: ArticleCustomFields;
+}
+```
+
+Now let's create a new `ArticleService` to handle the business logic of our new entity:
+
+```bash
+npx vendure add --service ArticleService --selected-plugin CmsPlugin --selected-entity Article
+```
+
+The service will be created in the `./src/plugins/cms/services` directory.
+
+Finally, we'll extend the GraphQL API to expose those CRUD operations:
+
+```bash
+npx vendure add --api-extension CmsPlugin --selected-service ArticleService --query-name ArticleQuery
+```
+
+Now the api extensions and resolver has been created in the `./src/plugins/cms/api-extensions` directory.
+
+The last step is to create a migration for our newly-created entity:
+
+```bash
+npx vendure migrate --generate article
+```
+
+Your project should now have the following structure:
+
+```
+src
+└── plugins/
+    └── cms/
+        ├── api/
+        │   ├── api-extensions.ts
+        │   └── article-admin.resolver.ts
+        ├── entities/
+        │   └── article.entity.ts
+        ├── services/
+        │   └── article.service.ts
+        ├── cms.plugin.ts
+        ├── constants.ts
+        └── types.ts
+```
+
+## Add Dashboard to Plugin
+
+Dashboard extensions are declared directly on the plugin metadata. Unlike the old AdminUiPlugin, you do not need to separately
+declare ui extensions anywhere except on the plugin itself.
+
+```ts title="src/plugins/cms/cms.plugin.ts"
+@VendurePlugin({
+    // ...
+    entities: [Article],
+    adminApiExtensions: {
+        schema: adminApiExtensions,
+        resolvers: [ArticleAdminResolver],
+    },
+    // highlight-next-line
+    dashboard: './dashboard/index.tsx',
+})
+export class CmsPlugin {
+    // ...
+}
+```
+
+You can do this automatically with the CLI command:
+
+```bash
+npx vendure add --dashboard CmsPlugin
+```
+
+This will add the `dashboard` property to your plugin as above, and will also create the `/dashboard/index.tsx` file
+which looks like this:
+
+```tsx title="src/plugins/cms/dashboard/index.tsx"
+import { Button, defineDashboardExtension, Page, PageBlock, PageLayout, PageTitle } from '@vendure/dashboard';
+import { useState } from 'react';
+
+defineDashboardExtension({
+    routes: [
+        // Here's a custom page so you can test that your Dashboard extensions are working.
+        // You should be able to access this page via the "Catalog > Test Page" nav menu item.
+        {
+            path: '/test',
+            loader: () => ({ breadcrumb: 'Test Page' }),
+            navMenuItem: {
+                id: 'test',
+                title: 'Test Page',
+                sectionId: 'catalog',
+            },
+            component: () => {
+                const [count, setCount] = useState(0);
+                return (
+                    <Page pageId="test-page">
+                        <PageTitle>Test Page</PageTitle>
+                        <PageLayout>
+                            <PageBlock column="main" blockId="counter">
+                                <p>Congratulations, your Dashboard extension is working!</p>
+                                <p className="text-muted-foreground mb-4">
+                                    As is traditional, let's include a counter:
+                                </p>
+                                <Button variant="secondary" onClick={() => setCount(c => c + 1)}>
+                                    Clicked {count} times
+                                </Button>
+                            </PageBlock>
+                        </PageLayout>
+                    </Page>
+                );
+            },
+        },
+    ],
+    // The following extension points are only listed here
+    // to give you an idea of all the ways that the Dashboard
+    // can be extended. Feel free to delete any that you don't need.
+    pageBlocks: [],
+    navSections: [],
+    actionBarItems: [],
+    alerts: [],
+    widgets: [],
+    customFormComponents: {},
+    dataTables: [],
+    detailForms: [],
+    login: {},
+    historyEntries: [],
+});
+```
+
+## IDE GraphQL Integration
+
+When extending the dashboard, you'll very often need to work with GraphQL documents for fetching data and executing mutations.
+
+Plugins are available for most popular IDEs & editors which provide auto-complete and type-checking for GraphQL operations
+as you write them. This is a huge productivity boost, and is **highly recommended**.
+
+- [GraphQL extension for VS Code](https://marketplace.visualstudio.com/items?itemName=GraphQL.vscode-graphql)
+- [GraphQL plugin for IntelliJ](https://plugins.jetbrains.com/plugin/8097-graphql) (including WebStorm)
+
+:::cli
+Run the `npx vendure schema` to generate a GraphQL schema file that your IDE plugin
+can use to provide autocomplete.
+:::
+
+1. Install the GraphQL plugin for your IDE
+2. Run `npx vendure schema --api admin` to generate a `schema.graphql` file in your root directory
+3. Create a `graphql.config.yml` file in your root directory with the following content:
+   ```yaml title="graphql.config.yml"
+   schema: 'schema.graphql'
+   ```
+
+## Dev Mode
+
+Once you have logged in to the dashboard, you can toggle on "Dev Mode" using the user menu in the bottom left:
+
+![Dev Mode](./dev-mode.webp)
+
+In Dev Mode, hovering any block in the dashboard will allow you to find the corresponding `pageId` and `blockId` values, which you can later use when customizing the dashboard. This is essential for:
+
+- Identifying where to place custom page blocks
+- Finding action bar locations
+- Understanding the page structure
+
+![Finding the location ids](./location-id.webp)
+
+## What's Next?
+
+Now that you understand the fundamentals of extending the dashboard, explore these specific guides:
+
+- [Creating Pages](/guides/extending-the-dashboard/creating-pages/) 
+- [Customizing Pages](/guides/extending-the-dashboard/customizing-pages/) 
+- [Navigation](/guides/extending-the-dashboard/navigation/) 

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

@@ -0,0 +1,194 @@
+---
+title: 'Getting Started'
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+:::info
+From Vendure v3.5.0, the `@vendure/dashboard` package and configuration comes as standard with new projects that are started with
+the `npx @vendure/create` command.
+
+This guide serves mainly for those adding the Dashboard to existing project set up prior to v3.5.0.
+:::
+
+## Installation & Setup
+
+:::note
+This guide assumes an existing project based on the `@vendure/create` folder structure.
+If you have a different setup (e.g. an Nx monorepo), you may need to adapt the instructions accordingly.
+:::
+
+First install the `@vendure/dashboard` package:
+
+```bash
+npm install @vendure/dashboard
+```
+
+Then create a `vite.config.mts` file in the root of your project (on the same level as your `package.json`) with the following content:
+
+```ts title="vite.config.mts"
+import { vendureDashboardPlugin } from '@vendure/dashboard/vite';
+import { join, resolve } from 'path';
+import { pathToFileURL } from 'url';
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+    base: '/dashboard',
+    build: {
+        outDir: join(__dirname, 'dist/dashboard'),
+    },
+    plugins: [
+        vendureDashboardPlugin({
+            // The vendureDashboardPlugin will scan your configuration in order
+            // to find any plugins which have dashboard extensions, as well as
+            // to introspect the GraphQL schema based on any API extensions
+            // and custom fields that are configured.
+            vendureConfigPath: pathToFileURL('./src/vendure-config.ts'),
+            // Points to the location of your Vendure server.
+            api: { host: 'http://localhost', port: 3000 },
+            // When you start the Vite server, your Admin API schema will
+            // be introspected and the types will be generated in this location.
+            // These types can be used in your dashboard extensions to provide
+            // type safety when writing queries and mutations.
+            gqlOutputPath: './src/gql',
+        }),
+    ],
+    resolve: {
+        alias: {
+            // This allows all plugins to reference a shared set of
+            // GraphQL types.
+            '@/gql': resolve(__dirname, './src/gql/graphql.ts'),
+        },
+    },
+});
+```
+
+You should also add the following to your existing `tsconfig.json` file to exclude the dashboard extensions and Vite config
+from your build, and reference a new `tsconfig.dashboard.json` that will have compiler settings for the Dashboard code.
+
+```json title="tsconfig.json"
+{
+    // ... existing options
+    "exclude": [
+        "node_modules",
+        "migration.ts",
+        "src/plugins/**/ui/*",
+        "admin-ui",
+        // highlight-start
+        "src/plugins/**/dashboard/*",
+        "src/gql/*",
+        "vite.*.*ts"
+        // highlight-end
+    ],
+    // highlight-start
+    "references": [
+        {
+            "path": "./tsconfig.dashboard.json"
+        }
+    ]
+    // highlight-end
+}
+```
+
+Now create a new `tsconfig.dashboard.json` to allow your IDE
+to correctly resolve imports of GraphQL types & interpret JSX in your dashboard extensions:
+
+```json title="tsconfig.dashboard.json"
+{
+    "compilerOptions": {
+        "composite": true,
+        "module": "ESNext",
+        "moduleResolution": "bundler",
+        "jsx": "react-jsx",
+        "paths": {
+            // Import alias for the GraphQL types
+            // Please adjust to the location that you have set in your `vite.config.mts`
+            "@/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/*"
+            ]
+        }
+    },
+    "include": [
+        "src/plugins/**/dashboard/*",
+        "src/gql/**/*.ts"
+    ]
+}
+```
+
+### Monorepo Setup
+
+If your project uses a monorepo structure, such as with Nx or Turborepo, then you'll need to make some adjustments
+to the paths given above:
+
+If each Vendure plugin is its own "package", outside the main Vendure server app, then it would need its own
+tsconfig for each plugin package. You might run into errors like:
+
+```
+Error loading Vendure config: Cannot find module
+```
+
+In this case, you'll need to configure a [PathAdapter](/reference/dashboard/vite-plugin/vendure-dashboard-plugin#pathadapter).
+
+You should also put your `vite.config.mts` file into the Vendure app directory rather than the root.
+
+## The DashboardPlugin
+
+In your `vendure-config.ts` file, you should also import and configure the [DashboardPlugin](/reference/core-plugins/dashboard-plugin/).
+
+```ts title="src/vendure-config.ts"
+import { DashboardPlugin } from '@vendure/dashboard/plugin';
+
+const config: VendureConfig = {
+    plugins: [
+        // ... existing plugins
+        // highlight-start  
+        DashboardPlugin.init({
+            // The route should correspond to the `base` setting
+            // in the vite.config.mts file
+            route: 'dashboard',
+            // This appDir should correspond to the `build.outDir`
+            // setting in the vite.config.mts file
+            appDir: './dist/dashboard',
+        }),
+        // highlight-end  
+    ],
+};
+```
+
+The `DashboardPlugin` adds the following features that enhance the use of the Dashboard:
+
+- It exposes a set of queries which power the Insights page metrics.
+- It registers SettingsStore entries that are used to store your personal display settings on the server side, which
+  allow administrators to enjoy a consistent experience across browsers and devices.
+- It serves the dashboard with a static server at the `/dashboard` route (by default), meaning you do not
+  need to set up a separate web server.
+
+## Running the Dashboard
+
+Once the above is set up, you can run `npm run dev` to start your Vendure server, and then visit
+
+```
+http://localhost:3000/dashboard
+```
+
+which will display a developer placeholder until you start the Vite dev server using
+
+```bash
+npx vite
+```
+
+To stop the running dashboard, type `q` and hit enter.
+
+:::info Compatibility with the legacy Admin UI
+If you still need to run the legacy Angular-based Admin UI in parallel with the Dashboard,
+this is totally possible. Both plugins can now be used simultaneously without any special configuration.
+:::

package/docs/guides/extending-the-dashboard/localization/index.md

@@ -0,0 +1,94 @@
+---
+title: 'Localization'
+---
+
+:::note
+Support for localization of Dashboard extensions was added in v3.5.1
+:::
+
+The Dashboard uses [Lingui](https://lingui.dev/), which provides a powerful i18n solution for React:
+
+- ICU MessageFormat support
+- Automatic message extraction
+- TypeScript integration
+- Pluralization support
+- Compile-time optimization
+
+## Wrap your strings
+
+First you'll need to wrap any strings that need to be localized:
+
+```tsx
+import { Trans, useLingui } from '@lingui/react/macro';
+
+function MyComponent() {
+    const { t } = useLingui();
+
+    return (
+        <div>
+            <h1>
+                // highlight-next-line
+                <Trans>Welcome to Dashboard</Trans>
+            </h1>
+            // highlight-next-line
+            <p>{t`Click here to continue`}</p>
+        </div>
+    );
+}
+```
+
+You will mainly make use of the [Trans component](https://lingui.dev/ref/react#trans)
+and the [useLingui hook](https://lingui.dev/ref/react#uselingui).
+
+## Extract translations
+
+Create a `lingui.config.js` file in your project root, with references to any plugins that need to be localized:
+
+```js title="lingui.config.js
+import { defineConfig } from '@lingui/cli';
+
+export default defineConfig({
+    sourceLocale: 'en',
+    // Add any locales you wish to support
+    locales: ['en', 'de'],
+    catalogs: [
+        // For each plugin you want to localize, add a catalog entry
+        {
+            // This is the output location of the generated .po files
+            path: '<rootDir>/src/plugins/reviews/dashboard/i18n/{locale}',
+            // This is the pattern that tells Lingui which files to scan
+            // to extract translation strings
+            include: ['<rootDir>/src/plugins/reviews/dashboard/**'],
+        },
+    ],
+});
+```
+
+Then extract the translations:
+
+```bash
+npx lingui extract
+```
+
+This will output the given locale files in the directories specified in the config file above.
+In this case:
+
+```
+src/
+└── plugins/
+    └── reviews/
+        └── dashboard/
+            └── i18n/
+                ├── en.po
+                └── de.po
+```
+
+Since we set the "sourceLocale" to be "en", the `en.po` file will already be complete. You'll then need to
+open up the `de.po` file and add German translations for each of the strings, by filling out the empty `msgstr` values:
+
+```po title="de.po"
+#: test-plugins/reviews/dashboard/review-list.tsx:51
+msgid "Welcome to Dashboard"
+// highlight-next-line
+msgstr "Willkommen zum Dashboard"
+```