@vendure/docs 0.0.0-202601161541

package/docs/guides/extending-the-dashboard/customizing-pages/page-blocks.md

@@ -0,0 +1,244 @@
+---
+title: 'Page Blocks'
+---
+
+In the Dashboard, all pages are built from blocks. Every block has a `pageId` and a `blockId` which uniquely locates it in the
+app (see [Dev Mode](/guides/extending-the-dashboard/extending-overview/#dev-mode) section).
+
+You can also define your own blocks, which can be added to any page and can even replace the default blocks.
+
+:::info
+All available options are documented in the [DashboardPageBlockDefinition reference](/reference/dashboard/extensions-api/page-blocks#dashboardpageblockdefinition)
+:::
+
+## Basic Page Block Example
+
+Here's an example of how to define a custom page block:
+
+```tsx title="src/plugins/my-plugin/dashboard/index.tsx"
+import { defineDashboardExtension } from '@vendure/dashboard';
+
+defineDashboardExtension({
+    pageBlocks: [
+        {
+            id: 'related-articles',
+            title: 'Related Articles',
+            location: {
+                // This is the pageId of the page where this block will be
+                pageId: 'product-detail',
+                // can be "main", "side" or "full"
+                column: 'side',
+                position: {
+                    // Blocks are positioned relative to existing blocks on
+                    // the page.
+                    blockId: 'facet-values',
+                    // Can be "before", "after" or "replace"
+                    // Here we'll place it after the `facet-values` block.
+                    order: 'after',
+                },
+            },
+            component: ({ context }) => {
+                // In the component, you can use the `context` prop to
+                // access the entity and the form instance.
+                return <div className="text-sm">Articles related to {context.entity.name}</div>;
+            },
+        },
+    ],
+});
+```
+
+This will add a "Related Articles" block to the product detail page:
+
+![Related Articles page block](../getting-started/page-block.webp)
+
+## Block Positioning
+
+Page blocks can be positioned in three ways relative to existing blocks:
+
+### Before
+
+Places the block before the specified `blockId`:
+
+```tsx
+position: {
+    blockId: 'product-variants',
+    order: 'before'
+}
+```
+
+### After
+
+Places the block after the specified `blockId`:
+
+```tsx
+position: {
+    blockId: 'product-variants',
+    order: 'after'
+}
+```
+
+### Replace
+
+Replaces the existing block entirely:
+
+```tsx
+position: {
+    blockId: 'product-variants',
+    order: 'replace'
+}
+```
+
+## Block Columns
+
+Blocks can be placed in three columns:
+
+- **`main`**: The main content area (wider column on the left)
+- **`side`**: The sidebar area (narrower column on the right)
+- **`full`**: Takes up the full horizontal width. This is mostly useful for adding blocks to list pages
+
+## Context Data
+
+The `context` prop provides access to:
+
+- **`entity`**: The current entity being viewed/edited (e.g., Product, Customer, etc.)
+- **`form`**: The React Hook Form instance for the current page (if applicable)
+- **`route`**: Route information and parameters
+
+## Block Visibility
+
+The visibility of a block can be dynamically controlled using the `shouldRender` function. This function receives the same
+context object as the block component, and should return a boolean to determine whether the block should be rendered.
+
+```ts
+import { defineDashboardExtension } from '@vendure/dashboard';
+
+import { AdvancedTaxInfo } from './advanced-tax-info.tsx';
+
+defineDashboardExtension({
+    pageBlocks: [
+        {
+            id: 'advanced-tax-info',
+            location: {
+                pageId: 'product-variant-detail',
+                column: 'side',
+                position: {
+                    blockId: 'facet-values',
+                    order: 'after',
+                },
+            },
+            component: AdvancedTaxInfo,
+            shouldRender: context => {
+                // You can use custom and build-in hooks
+                // in this function
+                const { activeChannel } = useChannel();
+
+                const hasTaxSettings = context.entity?.customFields?.taxSettings
+                // This block will only render if the entity has the
+                // expected custom field data, and the active channel has
+                // the given tax setting
+                return hasTaxSettings && activeChannel.pricesIncludeTax === false;
+            },
+        },
+    ],
+});
+```
+
+:::tip
+The `shouldRender` function can be used to hide built-in blocks by combining it with the "replace" position
+on an existing blockId.
+:::
+
+## Advanced Example
+
+Here's a more complex example that shows different types of blocks:
+
+```tsx title="src/plugins/my-plugin/dashboard/index.tsx"
+import { defineDashboardExtension, Button } from '@vendure/dashboard';
+import { useState } from 'react';
+
+defineDashboardExtension({
+    pageBlocks: [
+        // Analytics block for product page
+        {
+            id: 'product-analytics',
+            title: 'Product Analytics',
+            location: {
+                pageId: 'product-detail',
+                column: 'side',
+                position: {
+                    blockId: 'product-assets',
+                    order: 'after',
+                },
+            },
+            component: ({ context }) => {
+                const product = context.entity;
+                return (
+                    <div className="space-y-2">
+                        <div className="text-sm text-muted-foreground">Last 30 days</div>
+                        <div className="grid grid-cols-2 gap-4">
+                            <div>
+                                <div className="text-2xl font-bold">142</div>
+                                <div className="text-xs text-muted-foreground">Views</div>
+                            </div>
+                            <div>
+                                <div className="text-2xl font-bold">23</div>
+                                <div className="text-xs text-muted-foreground">Orders</div>
+                            </div>
+                        </div>
+                    </div>
+                );
+            },
+        },
+        // Quick actions block
+        {
+            id: 'quick-actions',
+            title: 'Quick Actions',
+            location: {
+                pageId: 'product-detail',
+                column: 'main',
+                position: {
+                    blockId: 'product-variants',
+                    order: 'after',
+                },
+            },
+            component: ({ context }) => {
+                const [isProcessing, setIsProcessing] = useState(false);
+
+                const handleSync = async () => {
+                    setIsProcessing(true);
+                    // Simulate API call
+                    await new Promise(resolve => setTimeout(resolve, 2000));
+                    setIsProcessing(false);
+                };
+
+                return (
+                    <div className="flex gap-2">
+                        <Button variant="outline" onClick={handleSync} disabled={isProcessing}>
+                            {isProcessing ? 'Syncing...' : 'Sync to External System'}
+                        </Button>
+                        <Button variant="outline">Generate QR Code</Button>
+                    </div>
+                );
+            },
+        },
+    ],
+});
+```
+
+## Finding Block IDs
+
+To find the `pageId` and `blockId` values for positioning your blocks:
+
+1. Enable [Dev Mode](/guides/extending-the-dashboard/extending-overview/#dev-mode) in the dashboard
+2. Navigate to the page where you want to add your block
+3. Hover over existing blocks to see their IDs
+4. Use these IDs in your block positioning configuration
+
+:::tip Best Practices
+
+1. **Use descriptive IDs**: Choose clear, unique IDs for your blocks
+2. **Position thoughtfully**: Consider the user experience when placing blocks
+3. **Handle loading states**: Show appropriate loading indicators for async operations
+4. **Follow design patterns**: Use the dashboard's existing UI components for consistency
+5. **Test thoroughly**: Verify your blocks work correctly on different screen sizes
+:::

package/docs/guides/extending-the-dashboard/data-fetching/index.md

@@ -0,0 +1,126 @@
+---
+title: 'Data Fetching'
+---
+
+## API Client
+
+The API client is the primary way to send queries and mutations to the Vendure backend. It handles channel tokens and authentication automatically.
+
+### Importing the API Client
+
+```tsx
+import { api } from '@vendure/dashboard';
+```
+
+The API client exposes two main methods:
+
+- `query` - For GraphQL queries
+- `mutate` - For GraphQL mutations
+
+### Using with TanStack Query
+
+The API client is designed to work seamlessly with TanStack Query for optimal data fetching and caching:
+
+#### Query Example
+
+```tsx
+import { useQuery } from '@tanstack/react-query';
+import { api } from '@vendure/dashboard';
+import { graphql } from '@/gql';
+
+const getProductsQuery = graphql(`
+    query GetProducts($options: ProductListOptions) {
+        products(options: $options) {
+            items {
+                id
+                name
+                slug
+            }
+            totalItems
+        }
+    }
+`);
+
+function ProductList() {
+    const { data, isLoading, error } = useQuery({
+        queryKey: ['products'],
+        queryFn: () =>
+            api.query(getProductsQuery, {
+                options: {
+                    take: 10,
+                    skip: 0,
+                },
+            }),
+    });
+
+    if (isLoading) return <div>Loading...</div>;
+    if (error) return <div>Error: {error.message}</div>;
+
+    return <ul>{data?.products.items.map(product => <li key={product.id}>{product.name}</li>)}</ul>;
+}
+```
+
+#### Mutation Example
+
+```tsx
+import { useMutation, useQueryClient } from '@tanstack/react-query';
+import { api } from '@vendure/dashboard';
+import { graphql } from '@/gql';
+import { toast } from 'sonner';
+
+const updateProductMutation = graphql(`
+    mutation UpdateProduct($input: UpdateProductInput!) {
+        updateProduct(input: $input) {
+            id
+            name
+            slug
+        }
+    }
+`);
+
+function ProductForm({ product }) {
+    const queryClient = useQueryClient();
+
+    const mutation = useMutation({
+        mutationFn: input => api.mutate(updateProductMutation, { input }),
+        onSuccess: () => {
+            // Invalidate and refetch product queries
+            queryClient.invalidateQueries({ queryKey: ['products'] });
+            toast.success('Product updated successfully');
+        },
+        onError: error => {
+            toast.error('Failed to update product', {
+                description: error.message,
+            });
+        },
+    });
+
+    const handleSubmit = data => {
+        mutation.mutate({
+            id: product.id,
+            ...data,
+        });
+    };
+
+    return (
+        // Form implementation
+        <form onSubmit={handleSubmit}>{/* Form fields */}</form>
+    );
+}
+```
+
+## Type Safety
+
+The Dashboard Vite plugin incorporates [gql.tada](https://gql-tada.0no.co/), which gives you type safety _without_ any code generation step!
+
+It works by analyzing your Admin API schema (including all your custom fields and other API extensions), and outputs the results
+to a file - by default you can find it at `src/gql/graphql-env.d.ts`.
+
+When you then use the `import { graphql } from '@/gql'` function to define your queries and mutations, you get automatic
+type safety when using the results in your components!
+
+When you have the `@/gql` path mapping correctly [set up as per the getting started guide](/guides/extending-the-dashboard/getting-started/#installation--setup), you should see that
+your IDE is able to infer the TypeScript type of your queries and mutations, including the correct inputs and return
+types!
+
+![Type inference](./type-inference.webp)

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

@@ -0,0 +1,200 @@
+---
+title: 'Deployment'
+---
+
+The Vendure Dashboard offers flexible deployment options. You can either serve it directly through your Vendure Server using the `DashboardPlugin`, or host it independently as a static site.
+
+## Deployment Options
+
+### Option 1: Serve with DashboardPlugin
+
+The `DashboardPlugin` integrates seamlessly with your Vendure Server by:
+
+- Serving the React dashboard as static files
+- Handling routing for the dashboard UI
+- Providing a unified deployment experience
+
+### Option 2: Standalone Hosting
+
+The Vendure Dashboard can be hosted independently as a static site, since the build produces standard web assets (index.html, CSS, and JS files). This approach offers maximum flexibility for deployment on any static hosting service.
+
+## Serving with DashboardPlugin
+
+To configure the DashboardPlugin, follow these steps:
+
+### 1. Configure Vite Base Path
+
+Update your `vite.config.mts` to set the base path where the dashboard will be served:
+
+```typescript title="vite.config.mts"
+import { vendureDashboardPlugin } from '@vendure/dashboard/vite';
+import path from 'path';
+import { pathToFileURL } from 'url';
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+    // highlight-start
+    base: '/dashboard/',
+    // highlight-end
+    plugins: [
+        vendureDashboardPlugin({
+            vendureConfigPath: pathToFileURL('./src/vendure-config.ts'),
+            api: {
+                host: 'http://localhost',
+                port: 3000,
+            },
+            gqlOutputPath: path.resolve(__dirname, './src/gql/'),
+        }),
+    ],
+});
+```
+
+### 2. Add DashboardPlugin to Vendure Config
+
+:::info Angular Admin UI compatibility
+If you want to use the Angular Admin UI and the Dashboard together, both plugins can now be used simultaneously without any special configuration.
+:::
+
+Add the DashboardPlugin to your `vendure-config.ts`:
+
+```typescript title="src/vendure-config.ts"
+import { DashboardPlugin } from '@vendure/dashboard/plugin';
+import path from 'path';
+
+export const config: VendureConfig = {
+    // ... other config
+    plugins: [
+        // ... other plugins
+        DashboardPlugin.init({
+            // highlight-start
+            // Important: This must match the base path from vite.config.mts (without slashes)
+            route: 'dashboard',
+            // highlight-end
+            // Path to the Vite build output directory
+            appDir: path.join(__dirname, './dist'),
+        }),
+    ],
+};
+```
+
+## Building for Production
+
+Before deploying your Vendure application, build the dashboard:
+
+```bash
+npx vite build
+```
+
+This command creates optimized production files in the `dist` directory that the DashboardPlugin will serve.
+
+## Accessing the Dashboard
+
+Once configured and built, your dashboard will be accessible at:
+
+```
+http://your-server-url/dashboard/
+```
+
+## Configuration Options
+
+### DashboardPlugin Options
+
+| Option   | Type     | Description                                                                   |
+| -------- | -------- | ----------------------------------------------------------------------------- |
+| `route`  | `string` | The URL path where the dashboard will be served (must match Vite's base path) |
+| `appDir` | `string` | Path to the directory containing the built dashboard files                    |
+
+## Best Practices
+
+1. **Consistent Paths**: Always ensure the `route` in DashboardPlugin matches the `base` in your Vite config
+2. **Build Before Deploy**: Add the Vite build step to your deployment pipeline
+3. **Production Builds**: Use `npx vite build` for optimized production builds
+
+## Example Deployment Script
+
+```json title="package.json"
+{
+    "scripts": {
+        "build": "npm run build:server && npm run build:dashboard",
+        "build:server": "tsc",
+        "build:dashboard": "vite build",
+        "start:prod": "node ./dist/index.js"
+    }
+}
+```
+
+## Standalone Hosting
+
+The dashboard can be hosted independently from your Vendure Server on any static hosting service (Netlify, Vercel, AWS S3, etc.).
+
+### Configuration
+
+When hosting standalone, you must configure the dashboard to connect to your Admin API endpoint:
+
+```typescript title="vite.config.mts"
+import { vendureDashboardPlugin } from '@vendure/dashboard/vite';
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+    plugins: [
+        vendureDashboardPlugin({
+            vendureConfigPath: pathToFileURL('./src/vendure-config.ts'),
+            // highlight-start
+            api: {
+                host: process.env.VENDURE_API_HOST || 'https://api.mystore.com',
+                port: parseInt(process.env.VENDURE_API_PORT || '443'),
+            },
+            // highlight-end
+            gqlOutputPath: path.resolve(__dirname, './src/gql/'),
+        }),
+    ],
+});
+```
+
+:::warning Build-Time Variables
+Environment variables are resolved at **build time** and embedded as static strings in the final bundles. Ensure these variables are available during the build process, not just at runtime.
+:::
+
+### Build and Deploy
+
+1. **Build the dashboard:**
+   ```bash
+   npx vite build
+   ```
+
+2. **Deploy the contents of the `dist` directory to your hosting service**
+
+### CORS Configuration
+
+When hosting the dashboard separately, configure CORS on your Vendure Server:
+
+```typescript title="src/vendure-config.ts"
+export const config: VendureConfig = {
+    apiOptions: {
+        cors: {
+            origin: ['https://dashboard.mystore.com'],
+            credentials: true,
+        },
+    },
+    // ... other config
+};
+```
+
+## Troubleshooting
+
+### Dashboard Not Loading (DashboardPlugin)
+
+- Verify the `route` matches the `base` path in Vite config
+- Check that the build output exists in the specified `appDir`
+- Ensure the DashboardPlugin is properly initialized in your plugins array
+
+### 404 Errors on Dashboard Routes
+
+- Confirm the base path includes trailing slashes where needed
+- Verify the server is running and the plugin is loaded
+
+### Connection Issues (Standalone)
+
+- Verify the API host and port are correct
+- Check CORS configuration on your Vendure Server
+- Ensure environment variables were available during build