Virto Commerce

https://github.com/virtocommerce/vc-docs
Admin
Virto Commerce is an open-source platform for building extensible ecommerce applications. This...
Tokens:715,395
Snippets:8,477
Trust Score:8.5
Update:2 months ago
Show doc for...
Tokens:
Raw
================
LIBRARY RULES
================
- VirtoCommerce has edge (current, pre-production daily) and stable (production-ready, once in a quarter with hotfixes) releases. Always query the docs version matching the release you target.

================
CODE SNIPPETS
================
### Preview Specific Documentation

Source: https://github.com/virtocommerce/vc-docs/blob/main/README.md

Commands to navigate to a specific guide directory and start the local development server.

```bash
cd user-guide
mkdocs serve
```

```bash
cd developer-guide
mkdocs serve
```

--------------------------------

### Setup Virtual Environment

Source: https://github.com/virtocommerce/vc-docs/blob/main/README.md

Commands to create and activate a Python 3.10+ virtual environment and install project dependencies.

```bash
# macOS / Linux
python3.10 -m venv .venv
source .venv/bin/activate
pip install -r requirements-docs.txt
```

```powershell
# Windows
py -3.10 -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements-docs.txt
```

--------------------------------

### NonProduct Class Query Example

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/Fundamentals/Intent-Search/examples.md

Demonstrates how a query like 'how to install the software' is analyzed by the NonProduct class, identifying it as a 'Support Question' with a high confidence score and suggesting relevant follow-up queries.

```json
// Input: "how to install the software"
{
  "searchText": "how to install the software",
  "response": {
    "tokenAnalysis": [
      {
        "token": "how to install the software",
        "detectedClass": "NonProduct",
        "matchedValue": "Support Question",
        "category": "Installation Help",
        "confidence": 0.90
      }
    ],
    "suggestedQueries": [
      "installation guide",
      "setup instructions",
      "technical support"
    ]
  }
}
```

--------------------------------

### Install the VirtoCommerce Global Tool

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/Getting-Started/Installation-Guide/start-local.md

Required prerequisite to install the global tool before running the local setup script.

```powershell
dotnet tool install VirtoCommerce.GlobalTool -g
```

--------------------------------

### Initialize and install platform from scratch

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/CLI-tools/install-and-update-platform-and-modules.md

Creates a new directory and installs the latest stable version of the platform and modules.

```bash
mkdir platform && cd platform
```

```bash
vc-build install
```

--------------------------------

### Setup Storefront Theme

Source: https://github.com/virtocommerce/vc-docs/blob/main/storefront/developer-guide/docs/vue-js-starter-theme/getting-started.md

Clones a theme repository and installs its dependencies using yarn. Ensure the `{store-code}` placeholder is replaced with your shop's code.

```bash
# Clone repo into the folder where storefront is installed
# `store-code` can be found in the platform running locally. More -> Shops -> Shop Name -> Code
git clone https://github.com/VirtoCommerce/vc-theme-b2b-vue.git "C:\vc-storefront\VirtoCommerce.Storefront\wwwroot\cms-content\themes\{store-code}\default"
# Change the current directory
cd C:\vc-storefront\VirtoCommerce.Storefront\VirtoCommerce.Storefront\wwwroot\cms-content\themes\{store-code}\default
# install dependencies
yarn install
```

--------------------------------

### Install VirtoCommerce.GlobalTool

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/CLI-tools/getting-started.md

Installs the global tool using the .NET CLI.

```console
dotnet tool install VirtoCommerce.GlobalTool  -g
```

--------------------------------

### Full Module Manifest Example

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/Fundamentals/Modularity/06-module-manifest-file.md

A complete example of a module.manifest file structure.

```xml
<module xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">

  <id>VirtoCommerce.Cart</id>
  <version>3.27.0</version>
  <version-tag>beta001</version-tag>
  <platformVersion>3.62.0</platformVersion>
  <title>Shopping cart module</title>
  <description>Shopping cart / checkout functionality</description>
  <authors>
    <author>Virto Commerce</author>
  </authors>
  <owners>
    <owner>Virto Commerce</owner>
  </owners>
  <projectUrl>https://virtocommerce.com/apps/extensions/virto-shoppingcart-module</projectUrl>
  <iconUrl>Modules/$(VirtoCommerce.Cart)/Content/logo.png</iconUrl>
  <assemblyFile>VirtoCommerce.CartModule.Web.dll</assemblyFile>
  <moduleType>VirtoCommerce.CartModule.Web.Module, VirtoCommerce.CartModule.Web</moduleType>
  <startupType>VirtoCommerce.CartModule.Web.CartModuleStartup, VirtoCommerce.CartModule.Web</startupType>
  <dependencies>
    <dependency id="VirtoCommerce.Core" version="3.22.0" />
    <dependency id="VirtoCommerce.Export" version="3.800.0" optional="True" />
  </dependencies>
</module>
```

--------------------------------

### Configure CI/CD Pipeline for VC Shell

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/custom-apps-development/vc-shell/guides/deployment.md

Example GitHub Actions workflow steps to install dependencies, lint, type-check, build the frontend, and publish the .NET module.

```yaml
- run: cd src/MyModule.Web/App && yarn install --immutable
- run: cd src/MyModule.Web/App && yarn lint
- run: cd src/MyModule.Web/App && yarn type-check
- run: cd src/MyModule.Web/App && yarn build
- run: dotnet publish src/MyModule.Web/MyModule.Web.csproj -c Release
- run: <upload .nupkg or copy publish output to the Platform>
```

--------------------------------

### vc-package.json Manifest Example

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/CLI-tools/install-and-update-platform-and-modules.md

Example configuration file defining various module sources and versions.

```json
{
  "Sources": [
    {
      "Name": "GithubReleases",
      "ModuleSources": [
        "https://raw.githubusercontent.com/VirtoCommerce/vc-modules/master/modules_v3.json"
      ],
      "Modules": [
        {
          "Id": "VirtoCommerce.Assets",
          "Version": "3.200.0"
        }
      ]
    },
    {
      "Name": "GithubPrivateRepos",
      "Owner": "VirtoCommerce",
      "Modules": [
        {
          "Id": "vc-module-custom",
          "Version": "3.16.0"
        }
      ]
    },
    {
      "Name": "AzurePipelineArtifacts",
      "Organization": "<Azure DevOps Organization>",
      "Project": "<Project name>",
      "Modules": [
        {
          "Id": "vc-module-custom",
          "Version": "3.14.0",
          "Branch": "<Branch name>",
          "Definition": "<Pipeline definition name or ID>"
        }
      ]
    },
    {
      "Name": "AzureUniversalPackages",
      "Organization": "https://dev.azure.com/<YOUR_ORGANIZATION>",
      "Feed": "<FEED_NAME>",
      "Project": "<YOUR_PROJECT_NAME>",
      "Modules": [
        {
          "Id": "<PACKAGE_NAME>",
          "Version": "<PACKAGE_VERSION>"
        }
      ]
    },
    {
      "Name": "AzureBlob",
      "Modules": [
        {
          "BlobName": "CustomCompany.CustomModule1_3.200.0.zip"
        }
      ],
      "Container": "modules",
      "ServiceUri": "https://vcpsblob.blob.core.windows.net"
    },
    {
      "Name": "GitlabJobArtifacts",
      "Modules": [
        {
          "JobId": "3679907995",
          "ArtifactName": "artifacts/VirtoCommerce.Catalog_3.255.0.zip",
          "Id": "42920184"
        }
      ]
    },
    {
      "Name": "Local",
      "Modules": [
        {
          "Path": "C:/projects/vc/vc-module-saas/artifacts/VirtoCommerce.SaaS_3.214.0.zip",
          "Id": "OptionalForThisSource"
        },
        {
          "Path": "C:\\projects\\vc\\vc-module-catalog\\artifacts\\VirtoCommerce.Catalog"
        }
      ]
    }
  ],
  "ManifestVersion": "2.0",
  "PlatformVersion": "3.216.0"
}
```

--------------------------------

### Install vc-app skill by runtime

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/custom-apps-development/vc-shell/getting-started/install-vc-app-skill.md

Use these commands to install the skill based on your specific AI coding tool runtime.

```bash
# Claude Code / Cursor / GitHub Copilot
npx @vc-shell/vc-app-skill install

# OpenCode
npx @vc-shell/vc-app-skill install --runtime opencode

# Gemini CLI
npx @vc-shell/vc-app-skill install --runtime gemini

# Codex
npx @vc-shell/vc-app-skill install --runtime codex
```

--------------------------------

### Install Individual Modules

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/CLI-tools/install-and-update-platform-and-modules.md

Command to install a specific module onto an existing platform installation.

```bash
vc-build install -module VirtoCommerce.WhiteLabeling
```

--------------------------------

### Install a PBC Max

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/Updating-Virto-Commerce-Based-Project/pbcs.md

Use the vc-build command to install a PBC by specifying the path to its package.json manifest file.

```console
vc-build install -PackageManifestPath <path to package.json>
```

--------------------------------

### Start Application

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/custom-apps-development/vc-shell/getting-started/manual-platform-api-setup.md

Launch the development server to verify the connection to the Platform instance.

```bash
yarn serve
```

--------------------------------

### Install Virto Commerce Global Tool

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/deployment-on-cloud/docs/create-environment-via-cli-and-vc-build.md

Installs the Virto Commerce Global Tool. Ensure .NET SDK is installed.

```bash
dotnet tool install VirtoCommerce.GlobalTool  -g
```

--------------------------------

### Full Azure AD Configuration Example

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/Fundamentals/Security/extensions/adding-azure-as-sso-provider.md

A comprehensive example of the AzureAd configuration block within appsettings.json.

```json
	"AzureAd": {
		"Enabled": true,
		"AuthenticationType": "AzureAD",
		"AuthenticationCaption": "Azure Active Directory",
		"ApplicationId": "b6d8dc6a-6ddd-4497-ad55-d65f91ca7f50",
		"TenantId": "common",
		"ValidateIssuer" : "MultitenantAzureAD",
		"AzureAdInstance": "https://login.microsoftonline.com/",
		"DefaultUserType": "Manager",
		"UsePreferredUsername": false,
		"Priority": 0
	},
```

--------------------------------

### Control sample data installation via PowerShell

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/Getting-Started/Installation-Guide/start-local.md

Use these parameters to toggle sample data installation during build or startup scripts.

```powershell
.\build-VC-solution.ps1 -skipSampleData $true
```

```powershell
.\start-VC-solution.ps1 -skipSampleData $false
```

--------------------------------

### Install platform from a specific manifest

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/CLI-tools/install-and-update-platform-and-modules.md

Use this command to install the platform and modules based on a specific vc-package.json file path.

```bash
vc-build install -PackageManifestPath <path to vc-package.json>
```

--------------------------------

### Install Virto Commerce module templates

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/Tutorials-and-How-tos/Tutorials/module-templates-for-dotnet-new.md

Run this command to install the template package from NuGet.

```powershell
dotnet new install VirtoCommerce.Module.Template
```

--------------------------------

### Install Virto Commerce CLI

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/Getting-Started/Installation-Guide/linux.md

Install the global tool for managing Virto Commerce platform installations.

```console
dotnet tool install -g VirtoCommerce.GlobalTool
```

--------------------------------

### Install a PBC using the CLI

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/Getting-Started/Installation-Guide/pbcs.md

Use the vc-build command to install a specific PBC by providing the path to its package.json file.

```console
vc-build install -PackageManifestPath path to package.json
```

--------------------------------

### Example of buildInitialWeights calculation

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/data/table-composables.md

Conceptual example showing how initial weights are derived from column definitions given an available width.

```ts
// Example: three columns — 200px, 20%, auto — with 800px available
// px-column  → weight 200
// pct-column → weight 160  (20% of 800)
// auto-column→ weight 440  (800 - 200 - 160)
```

--------------------------------

### Serve Documentation

Source: https://github.com/virtocommerce/vc-docs/blob/main/README.md

Command to start the local development server for a specific documentation configuration file.

```bash
mkdocs serve -f platform/developer-guide/mkdocs.yml
# open http://127.0.0.1:8000
```

--------------------------------

### Preview the production bundle

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/custom-apps-development/vc-shell/guides/deployment.md

Starts a local static server to verify the production build before deployment.

```bash
yarn preview
```

--------------------------------

### Install Platform with CLI

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/CLI-tools/more-targets.md

Use the InstallPlatform command to install the Platform as defined in vc-package.json. This command provides the necessary components for the Platform's operation.

```console
vc-build InstallPlatform
```

--------------------------------

### Install platform via CLI

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/Getting-Started/Installation-Guide/linux.md

Commands to install the platform and modules using the CLI, with an optional version flag.

```console
vc-build install
```

```console
vc-build install -version 3.x.x.x
```

--------------------------------

### Start the development server

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/custom-apps-development/vc-shell/getting-started/your-first-module.md

Navigate to the project directory and launch the development server using Yarn.

```bash
cd books-app
yarn serve
```

--------------------------------

### Install Frontend Dependencies

Source: https://github.com/virtocommerce/vc-docs/blob/main/storefront/developer-guide/docs/deployment.md

Install all necessary dependencies for the Frontend Application using Yarn.

```bash
yarn install
```

--------------------------------

### Install Multiple Modules

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/Updating-Virto-Commerce-Based-Project/installing-specific-version.md

This command allows for the installation of multiple modules at once. List each module and its version separated by a space.

```bash
vc-build install -module <module1>:<version> <module2>:<version>
```

--------------------------------

### Install Platform via CLI

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/CLI-tools/install-and-update-platform-and-modules.md

Commands to install the latest or a specific version of the Virto Commerce platform.

```bash
vc-build install -platform
```

```bash
vc-build install -platform -version 3.854.7
```

--------------------------------

### Compile for Installation Artifact

Source: https://github.com/virtocommerce/vc-docs/blob/main/storefront/developer-guide/docs/vue-js-starter-theme/getting-started.md

Compiles the storefront application to generate an artifact suitable for installation.

```bash
yarn compress
```

--------------------------------

### Non-interactive Scaffolding Examples

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/custom-apps-development/vc-shell/reference/cli/create-vc-app.md

Examples of generating projects without interactive prompts using flags.

```bash
npx @vc-shell/create-vc-app my-app \
  --type standalone \
  --module-name "Products" \
  --dashboard \
  --mocks
```

```bash
npx @vc-shell/create-vc-app my-module \
  --type dynamic-module \
  --module-name "Reviews"
```

--------------------------------

### Standard robots.txt configuration

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/user-guide/docs/store/custom-robot-txt.md

A basic example showing how to restrict specific paths and provide a sitemap URL.

```text
User-agent: *                               // Applies the rule to all crawlers
Disallow: /admin/                           // Blocks indexing of the `/admin/` path 
Disallow: /checkout/                        // Blocks indexing of the `/checkout/` path
Allow: /                                    // Allows crawling of all other content
Sitemap: https://example.com/sitemap.xml    // Provides the URL of your site’s sitemap to improve indexing
```

--------------------------------

### Install Vitest dependencies

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/custom-apps-development/vc-shell/guides/testing-a-module.md

Install the necessary testing packages via yarn.

```bash
yarn add -D vitest @vue/test-utils jsdom @testing-library/jest-dom
```

--------------------------------

### Install specific modules by ID and version

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/CLI-tools/package-management.md

Syntax for installing individual Virto Commerce modules using either separate parameters or a colon-delimited string.

```console
vc-build install -module <moduleId> -version <version>
vc-build install -module <moduleId>:<version>
```

--------------------------------

### Install latest edge versions

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/CLI-tools/install-and-update-platform-and-modules.md

Installs the most recent available versions of the platform and modules.

```bash
vc-build install -edge
```

--------------------------------

### Install dependencies

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/Fundamentals/Testing/testing.md

Upgrades pip and installs required packages from the requirements file.

```csharp
python -m pip install --upgrade pip
pip install -r requirements.txt
```

--------------------------------

### Install Custom Modules with Authentication

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/CLI-tools/install-and-update-platform-and-modules.md

Command to install modules defined in a manifest file, including necessary authentication tokens.

```bash
vc-build install -PackageManifestPath ./vc-package.json -GithubToken ghp_XXXXXXXXXXXXXXXXXXX -AzureToken azp_YYYYYYYYYYYYYYY
```

--------------------------------

### Run Frontend Application

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/Fundamentals/Indexed-Search/integration/configuring-elastic-app-search.md

Executes the application build and start process using the .NET CLI.

```bash
dotnet run
```

--------------------------------

### Install Platform Stable Release

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/Updating-Virto-Commerce-Based-Project/stable-releases.md

Install the latest stable release or a specific version of the platform and modules.

```console
vc-build install
```

```console
vc-build install -v 7
```

--------------------------------

### Install specific bundle version

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/CLI-tools/install-and-update-platform-and-modules.md

Targets a specific bundle version for the platform and module installation.

```bash
vc-build install -v 9
```

--------------------------------

### Procedural Step Formatting

Source: https://github.com/virtocommerce/vc-docs/blob/main/CLAUDE.md

Example of how to introduce a procedure using a numbered list of links.

```markdown
To set up the Platform:

1. [Configure application strings](#link).
2. [Run the Platform](#link).
3. [Perform initial sign-in](#link).
```

--------------------------------

### Install Package with Custom Paths

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/Updating-Virto-Commerce-Based-Project/tips.md

Customize the installation process by specifying custom locations for the package manifest, discovery modules, and probing modules. This is useful for complex project structures.

```console
vc-build install -PackageManifestPath some_directory/vc-package.json -DiscoveryPath ../modules -ProbingPath platform_dir/app_data/modules
```

--------------------------------

### Install platform and module dependencies via CLI

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/CLI-tools/package-management.md

Commands for installing platform components and modules, including options for authentication, versioning, and custom path overrides.

```console
vc-build install
vc-build install -GitLabToken $GITLAB_TOKEN
vc-build install -platform -version <version>
vc-build install -platform -PlatformAssetUrl https://github.com/VirtoCommerce/vc-platform/releases/download/3.216.13/VirtoCommerce.Platform.3.216.13.zip
vc-build install -module <module> -version <version>
vc-build install -module <module>:<version>
vc-build install -PackageManifestPath some_directory/vc-package.json -DiscoveryPath ../modules -ProbingPath platform_dir/app_data/modules -SkipDependencySolving
```

--------------------------------

### Install Builder.io SDK for Vue 3

Source: https://github.com/virtocommerce/vc-docs/blob/main/storefront/developer-guide/docs/integrations/builder-io/overview_outdated.md

Install the `@builder.io/sdk-vue` package to enable integration. Version 0.3.1 is recommended for stability and compatibility.

```bash
yarn add @builder.io/sdk-vue@^0.3.1
```

--------------------------------

### Test Execution Output Example

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/CLI-tools/build-automation.md

Example output showing test results, coverage statistics, and build duration.

```console
vc-build test

Starting test execution, please wait...
A total of 1 test files matched the specified pattern.
Passed!  - Failed:     0, Passed:    48, Skipped:     0, Total:    48, Duration: 4 s - VirtoCommerce.CatalogCsvImportModule.Tests.dll (netcoreapp3.1)

Calculating coverage result...
Generating report 'c:\Projects\VirtoCommerce\V3\Modules\vc-module-catalog-csv-import\.tmp\coverage.xml'
++++
| Module                                    | Line   | Branch | Method |
++++
| VirtoCommerce.CatalogCsvImportModule.Core | 77,17% | 73,38% | 72,83% |
++++
| VirtoCommerce.CatalogCsvImportModule.Data | 56,47% | 52,15% | 56,86% |
++++

++++
|         | Line   | Branch | Method |
++++
| Total   | 65,23% | 60,64% | 66,66% |
++++
| Average | 66,81% | 62,76% | 64,84% |
++++


═══════════════════════════════════════
Target             Status      Duration
───────────────────────────────────────
Restore            Executed        0:04
Compile            Executed        0:08
Test               Executed        1:09
───────────────────────────────────────
Total                              1:22
═══════════════════════════════════════
```

--------------------------------

### Build Frontend

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/Tutorials-and-How-tos/Tutorials/deploy-module-from-source-code.md

Commands to install dependencies and build or watch frontend assets.

```console
cd src/VirtoCommerce.{module-name}.Web
```

```console
npm ci
```

```console
npm run webpack:build
```

```console
npm run webpack:watch
```

--------------------------------

### Scaffold a new VC application

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/custom-apps-development/vc-shell/getting-started/manual-cli-start.md

Initializes a new standalone application project and installs dependencies.

```bash
npx @vc-shell/create-vc-app my-app --type standalone
cd my-app
yarn install
yarn serve
```

--------------------------------

### Register the AI Agent Plugin

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/custom-apps-development/vc-shell/plugins/ai-agent.md

Install the plugin via environment variables or explicit configuration in the application setup.

```typescript
// Option 1: Via environment variable (recommended)
// Set APP_AI_AGENT_URL in your .env file
// The framework installs the plugin automatically.

// Option 2: Explicit installation
import { aiAgentPlugin } from "@vc-shell/framework";

app.use(aiAgentPlugin, {
  config: {
    url: "https://ai.example.com/chat",
    title: "AI Assistant",
    width: 400,
  },
  addGlobalToolbarButton: true,
});
```

--------------------------------

### Build and Install Adapter from Source

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/Tutorials-and-How-tos/How-tos/connect-to-ai-agents-via-onx.md

Commands to clone, build the server and adapter, and configure the local path in Claude Desktop.

```bash
git clone https://github.com/VirtoCommerce/vc-onX-adapter.git
cd vc-onX-adapter

# Build the server first — the adapter depends on it
cd server && npm install && npm run build && cd ..

# Build the adapter
cd virtocommerce-adapter && npm install && npm run build && cd ..
```

```json
{
  "mcpServers": {
    "cof-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/server/dist/index.js"],
      "env": {
        "ADAPTER_TYPE": "local",
        "ADAPTER_PATH": "/absolute/path/to/virtocommerce-adapter/dist/index.js",
        "ADAPTER_CONFIG": "{\"apiUrl\":\"https://your-vc-instance.com\",\"apiKey\":\"YOUR_API_KEY\",\"workspace\":\"your-store-id\"}",
        "LOG_LEVEL": "info"
      }
    }
  }
}
```

--------------------------------

### Registering the Permissions Plugin

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/custom-apps-development/vc-shell/plugins/permissions.md

The framework automatically installs this plugin during app setup, making the hasAccess function available globally.

```typescript
// Automatic -- installed by the framework during app setup.
// The plugin source is straightforward:
import { usePermissions } from "@vc-shell/framework";
import { App } from "vue";

export const permissions = {
  install(app: App) {
    const { hasAccess } = usePermissions();
    app.config.globalProperties.$hasAccess = hasAccess;
  },
};
```

--------------------------------

### Avoid useMenuService during module setup

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/services/useMenuService.md

Use standalone functions instead of useMenuService during the plugin installation phase to avoid InjectionErrors.

```typescript
// Wrong -- service is not provided yet during plugin install
export default {
  install(app) {
    const menuService = useMenuService(); // throws InjectionError
    menuService.addMenuItem({ ... });
  },
};

// Correct -- use the standalone function
export default {
  install(app) {
    addMenuItem({ title: "Orders", icon: "fas fa-cart", routeId: "OrdersList", priority: 10 });
  },
};
```

--------------------------------

### Initializing widgets during module setup

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/services/useDashboard.md

Use the standalone registerDashboardWidget function instead of useDashboard() during plugin installation to avoid injection errors.

```typescript
// Wrong -- service is not yet provided during plugin install
export default {
  install(app) {
    const dashboard = useDashboard(); // throws InjectionError
    dashboard.registerWidget({ ... });
  },
};

// Correct -- use the standalone function
export default {
  install(app) {
    registerDashboardWidget({ id: "widget", name: "W", component: Comp, size: { width: 1, height: 1 } });
  },
};
```

--------------------------------

### Quick Start with useTheme

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/ui-state/useTheme.md

Demonstrates how to register a custom theme, switch themes explicitly, and cycle through themes using the next() method.

```vue
<script setup lang="ts">
import { useTheme } from "@vc-shell/framework";

const { themes, currentThemeKey, currentLocalizedName, next, setTheme, register } = useTheme();

// light and dark are registered by default; register a custom theme from your module
register({ key: "ocean", localizationKey: "MY_MODULE.THEMES.OCEAN" });

// Switch to it explicitly
setTheme("ocean");

// Or cycle through all registered themes (light -> dark -> ocean -> light -> ...)
next();
</script>

<template>
  <div>
    <p>Current theme: {{ currentLocalizedName }} ({{ currentThemeKey }})</p>
    <VcButton @click="next">Next Theme</VcButton>
  </div>
</template>
```

--------------------------------

### Compress target output

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/CLI-tools/getting-started.md

Example output showing the execution status of various build steps.

```console
═══════════════════════════════════════
Target             Status      Duration
───────────────────────────────────────
Clean              Executed        0:00
Restore            Executed        0:07
Compile            Executed        0:06
WebPackBuild       Executed        0:00
Test               Executed        0:05
Publish            Executed        0:01
Compress           Executed        0:01
───────────────────────────────────────
Total                              0:23
═══════════════════════════════════════
```

--------------------------------

### Skip backup during installation

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/CLI-tools/install-and-update-platform-and-modules.md

Use this command to prevent the automatic creation of a backup when installing the platform in a directory that already contains files.

```bash
vc-build install -skip Backup
```

--------------------------------

### GET Dynamic Properties Response

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/Fundamentals/Dynamic-Properties/using-DynamicPropertyAccessor.md

Example of a JSON response structure where dynamic property values are returned directly under the dynamicPropertyAccessor object.

```json
{
  "dynamicPropertyAccessor": {
    "DateTimeFieldSingleValue": "2025-09-25T22:00:00Z",
    "DecimalFieldMultiValue": [678, 1011, 123, 345],
    "DecimalFieldSingleValue": 345.45,
    "HtmlFieldSingleValue": "<b>Hi</b>",
    "ImageFieldSingleValue": null,
    "IntegerFieldMiltiValue": [456, 123],
    "IntegerFieldSingleValue": 123,
    "LongTextFieldSingleValue": "Long text value...",
    "ShortTextFieldSingleValue": "Short text value",
    "ShortTextFieldSingleValue_Localized": {
      "values": {
        "en-US": null,
        "de-DE": null,
        "fr-FR": null,
        "ru-RU": null,
        "it-IT": null,
        "pl": null,
        "ja-JP": null
      }
    }
  },
  "createdBy": "unknown",
  "modifiedBy": "admin",
  "id": "cb0a5340-f9fb-4f49-bd62-9d03518868ff"
}
```

--------------------------------

### Initialize useAsync at setup time

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/utilities/useAsync.md

Define useAsync instances during component setup to ensure loading states are correctly tracked and accessible to templates.

```typescript
// BAD -- creates a new loading ref each call, template never sees it
async function loadData() {
  const { action, loading } = useAsync(async () => {
    /* ... */
  });
  await action();
}
```

```typescript
// GOOD -- create at setup time, call the action later
const { action: loadData, loading } = useAsync(async () => {
  /* ... */
});

onMounted(() => loadData());
```

--------------------------------

### Enable Application Insights at Install

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/custom-apps-development/vc-shell/guides/platform/index.md

Initialize Application Insights by passing the instrumentation key and app name during the VirtoShellFramework plugin installation.

```ts
import VirtoShellFramework from "@vc-shell/framework";

const app = createApp(RouterView);
app.use(VirtoShellFramework, {
  router,
  applicationInsights: {
    instrumentationKey: import.meta.env.APP_INSIGHTS_KEY,
    appName: "Seller Console",
  },
});
```

--------------------------------

### Install Package with Custom Manifest Path

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/Updating-Virto-Commerce-Based-Project/tips.md

Use this command to install packages when your vc-package.json is located in a custom directory or has a custom name. Ensure the path provided is correct.

```console
vc-build install -PackageManifestPath /path/package.json
```

--------------------------------

### Install Latest Edge Release of a Module

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/Updating-Virto-Commerce-Based-Project/edge-releases.md

Installs the latest edge release for a specific module. Replace `<moduleId>` with the actual ID of the module you wish to install.

```console
vc-build install -module <moduleId> -edge
```

--------------------------------

### Install Module Stable Release

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/Updating-Virto-Commerce-Based-Project/stable-releases.md

Install a specific module by its ID.

```console
vc-build install -module <moduleId>
```

--------------------------------

### CSV file example for product updates

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/user-guide/docs/catalog/import-products-to-catalog.md

Example of a CSV structure used to update specific product properties like Name and Size using the SKU identifier.

```csv
Sku,Name,Size
SKU123,New name,XXL
```

--------------------------------

### Install LibSass library

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/Getting-Started/Installation-Guide/macOS.md

Copy the extracted native library to the .NET shared runtime directory.

```console
sudo cp libsass/runtimes/osx-x64/native/libsass.dylib /usr/local/share/dotnet/shared/Microsoft.NETCore.App/10.x.x/
```

--------------------------------

### Uninstall locally installed templates

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/Tutorials-and-How-tos/Tutorials/module-templates-for-dotnet-new.md

Removes templates installed from a local directory path.

```powershell
dotnet new uninstall <full or relative path to the templates directory>
```

--------------------------------

### Run the connect command

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/custom-apps-development/vc-shell/getting-started/connect-to-platform.md

Execute this command within the application root to initiate the connection process.

```text
/vc-app connect
```

--------------------------------

### Configuration File for Certificate Generation

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/Tutorials-and-How-tos/How-tos/authorization-using-jwt.md

Example content for the certconfig.txt file required for OpenSSL certificate generation.

```text
[ req ]
default_md = sha256
prompt = no
req_extensions = req_ext
distinguished_name = req_distinguished_name
[ req_distinguished_name ]
commonName = virtocommerce.com
countryName = RU
stateOrProvinceName = Kaliningrad
organizationName = Virtocommerce
[ req_ext ]
subjectKeyIdentifier = hash
authorityKeyIdentifier = keyid:always,issuer
keyUsage=critical,digitalSignature,keyEncipherment
extendedKeyUsage=critical,serverAuth,clientAuth
subjectAltName = @alt_names
[ alt_names ]
DNS.0 = virtocommerce.com
```

--------------------------------

### Implement minimal VcApp setup

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/custom-apps-development/vc-shell/components/layout/vc-app.md

Initializes the VcApp component with reactive state for user profile data and readiness status.

```vue
<script setup lang="ts">
import { ref, onMounted } from "vue";
import { VcApp } from "@vc-shell/framework";

const isReady = ref(false);
const user = ref({ name: "", role: "" });

onMounted(async () => {
  const profile = await fetchUserProfile();
  user.value = profile;
  isReady.value = true;
});
</script>

<template>
  <VcApp
    :is-ready="isReady"
    logo="/img/logo.svg"
    title="My Admin"
    :name="user.name"
    :role="user.role"
  />
</template>
```

--------------------------------

### Install Storyblok SDK

Source: https://github.com/virtocommerce/vc-docs/blob/main/storefront/developer-guide/docs/integrations/storyblok/overview.md

Install the official Storyblok SDK for Vue 3 using yarn.

```bash
yarn add @storyblok/vue
```

--------------------------------

### Manage Notification Lifecycle

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/custom-apps-development/vc-shell/components/feedback/vc-toast.md

Example demonstrating basic creation, persistence, and manual removal of notifications.

```ts
notification("Quick flash", { timeout: 1500 });
const id = notification("Please wait...", { timeout: false });
notification.remove(id); // dismiss programmatically
```

--------------------------------

### Run promote command

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/custom-apps-development/vc-shell/getting-started/promote-prototype-to-api.md

Execute this command in the terminal to initiate the promotion of a specific module.

```text
/vc-app promote products
```

--------------------------------

### Start Elastic Cluster

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/Fundamentals/Indexed-Search/integration/configuring-elastic-app-search.md

Command to initialize the Elastic cluster using Docker Compose.

```bash
docker-compose up
```

--------------------------------

### Install or update dotnet-ef

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/Tutorials-and-How-tos/How-tos/upgrading-to-dot-net-10.md

Commands to manage the Entity Framework Core tools for .NET 10.

```cmd
dotnet tool install --global dotnet-ef --version 10.0.1
```

```cmd
dotnet tool update --global dotnet-ef --version 10.0.1
```

--------------------------------

### Initialize vc-package.json with CLI

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/CLI-tools/more-targets.md

Use the Init command to create a vc-package.json file with initial content, including the latest Platform version. This file is foundational for managing Platform and module versions.

```console
vc-build Init
```

```console
vc-build Init -PlatformVersion 3.52.0
```

--------------------------------

### setBroadcastFilter

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/notifications/useBroadcastFilter.md

Installs a filter function to determine which broadcast notifications should be accepted. Replaces any previously installed filter.

```APIDOC
## setBroadcastFilter(fn: (msg: PushNotification) => boolean)

### Description
Installs a filter function that evaluates incoming broadcast notifications. The function should return `true` to accept the message or `false` to drop it.

### Parameters
- **fn** (function) - Required - A callback function that receives a `PushNotification` object and returns a boolean.
```

--------------------------------

### Publish Application

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/CLI-tools/build-automation.md

Prepares the application for deployment by packaging dependencies.

```console
vc-build publish
```

--------------------------------

### Build Multi-site Documentation

Source: https://github.com/virtocommerce/vc-docs/blob/main/README.md

Command to build all sub-sites into the ./site directory.

```bash
./build.sh    # builds every sub-site into ./site
```

--------------------------------

### Install dotnet-script Tool

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/GraphQL-Storefront-API-Reference-xAPI/update-xapi-modules.md

Command to install the dotnet-script global tool required to execute the update script.

```bash
dotnet tool install -g dotnet-script
```

--------------------------------

### Configure Environment Variables

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/Tutorials-and-How-tos/How-tos/docker-modules-development.md

Examples of setting environment variables in the .env file for module paths, platform versions, and search providers.

```cmd
APP_DATA_MODULES=c:\path\to\folder\modules
```

```cmd
PLATFORM_VERSION=dev-linux-latest
...
SEARCH_PROVIDER=ElasticSearch
```

--------------------------------

### Markdown Content Example

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/Extensibility/cms-integrations/PageBuilder/markdown.md

Example of content structure for the Markdown control, showing both markdown and html representations.

```json
{
    "content": [
        {
            "type": "markdown-example",
            "content": {
                "markdown": "## Markdown example",
                "html": "<h2>Markdown example</h2>"
            }
        }
    ] 
}
```

--------------------------------

### Create API Controller

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/Tutorials-and-How-tos/Tutorials/creating-custom-module.md

Defines a controller with POST and GET endpoints for managing blog entities.

```csharp
using System.Threading.Tasks;
    using Microsoft.AspNetCore.Mvc;
    using MyCoolCompany.MyCoolModule.Core.Models;
    using MyCoolCompany.MyCoolModule.Core.Services;

    namespace MyCoolCompany.MyCoolModule.Web.Controllers.Api
    {
        [Route("api/my-cool-module")]
        public class MyCoolModuleController : Controller
        {
            private readonly IBlogService _blogService;
            private readonly IBlogSearchService _blogSearchService;

            public MyCoolModuleController(
                IBlogService blogService,
                IBlogSearchService blogSearchService)
            {
                _blogService = blogService;
                _blogSearchService = blogSearchService;
            }

            [HttpPost]
            [Route("")]
            public async Task<ActionResult<Blog>> AddBlog(string name)
            {
                var blog = new Blog { Name = name };

                await _blogService.SaveChangesAsync([blog]);

                return Ok(blog);
            }

            [HttpGet]
            [Route("")]
            public async Task<ActionResult<BlogSearchResult>> GetAll()
            {
                var result = await _blogSearchService.SearchAsync(new BlogSearchCriteria());

                return Ok(result);
            }
        }
    }
```

--------------------------------

### Manage modules via CLI

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/Fundamentals/Modularity/01-overview.md

Commands for installing specific modules or updating the entire platform environment.

```bash
vc-build install -Module VirtoCommerce.Store
```

```bash
vc-build update
```

--------------------------------

### Execute vc-build commands

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/CLI-tools/getting-started.md

Basic commands for running build targets and viewing help documentation.

```console
vc-build
```

```console
vc-build help
```

```console
vc-build help NameOfTheTarget
```

--------------------------------

### Build Backend from CLI

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/Tutorials-and-How-tos/Tutorials/deploy-module-from-source-code.md

Navigate to the backend project directory and build the project using the .NET CLI.

```console
cd src/VirtoCommerce.{module-name}.Web
```

```console
dotnet build -c Development
```

--------------------------------

### Install Eland Python Client

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/Fundamentals/Indexed-Search/integration/semantic-search-es9.md

Use pip to install the Eland client required for importing models into Elasticsearch.

```cmd
pip install eland
```

--------------------------------

### Example store update path

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/Tutorials-and-How-tos/How-tos/upgrading-to-dot-net-10.md

A specific example of a store update path that may trigger the 415 error.

```txt
 /api/stores/B2B-store
```

--------------------------------

### Post-Scaffold Commands

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/custom-apps-development/vc-shell/reference/cli/create-vc-app.md

Standard commands to initialize and run the generated project.

```bash
cd <project-name>
yarn install
yarn serve
```

--------------------------------

### Text Control Settings Example

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/Extensibility/cms-integrations/PageBuilder/text.md

Example JSON structure for text control settings, including a caption field.

```json
{
    "settings": [
        {
            "id": "caption",
            "type": "text",
            "label": "Caption",
            "default": "Lorem ipsum"
        },
        ...
    ]
}
```

--------------------------------

### Scaffold and generate modules in two steps

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/custom-apps-development/vc-shell/getting-started/your-first-module.md

Manually scaffold the project and then interactively generate modules for more granular control.

```bash
npx @vc-shell/create-vc-app@latest books-app --type standalone
yarn install
cd books-app
/vc-app generate
```

--------------------------------

### Start Docker containers in build mode

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/Tutorials-and-How-tos/How-tos/docker-modules-development.md

Starts the containers in detached mode after rebuilding images from the current directory.

```powershell
docker-compose up --build -d
```

--------------------------------

### Run Platform via CLI

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/Getting-Started/Installation-Guide/windows.md

Commands to start the platform using the .NET CLI with specified URLs.

```console
cd C:\vc-platform-3\
dotnet VirtoCommerce.Platform.Web.dll --urls "https://localhost:5001;http://localhost:5000"
```

```console
Now listening on: http://localhost:5000
Now listening on: https://localhost:5001
```

```console
dotnet VirtoCommerce.Platform.Web.dll --urls=http://localhost:5000
```

--------------------------------

### Query installed modules using IModuleService

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/Tutorials-and-How-tos/How-tos/upgrading-to-stable-15.md

Implement IHasModuleService in the module class to access IModuleService for checking installed modules.

```csharp
public class Module : IModule, IHasModuleService
{
    public IModuleService ModuleService { get; set; }

    public void PostInitialize(IApplicationBuilder appBuilder)
    {
        if (ModuleService.IsInstalled("VirtoCommerce.WhiteLabeling"))
        {
            // ...
        }
    }
}
```

--------------------------------

### Download precompiled binaries

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/Getting-Started/Installation-Guide/linux.md

Download the platform release ZIP file from GitHub using wget.

```console
wget "https://github.com/VirtoCommerce/vc-platform/releases/download/3.x.x/VirtoCommerce.Platform.3.x.x.zip"
```

--------------------------------

### Register IPlatformStartup Implementation in module.manifest

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/Fundamentals/Modularity/IPlatformStartup.md

Declare the startup type in your module's manifest file to register an IPlatformStartup implementation. The platform automatically discovers and invokes it.

```xml
<startupType>VirtoCommerce.MyModule.MyModuleStartup, VirtoCommerce.MyModule</startupType>
```

--------------------------------

### Example Search Queries

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/Fundamentals/Indexed-Search/search-query-syntax-reference.md

Illustrates different ways to use the search query syntax for various search needs.

```text
Red wine
```

```text
"Red wine"
```

```text
"\"Red wine\""
```

--------------------------------

### Using Translations in Script Setup

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/custom-apps-development/vc-shell/plugins/i18n.md

Use the useI18n composable to access translation functions within the script setup block.

```vue
<script setup lang="ts">
import { useI18n } from "vue-i18n";

const { t } = useI18n();

const pageTitle = computed(() => t("ORDERS.PAGES.DETAILS.TITLE"));

// With interpolation
const greeting = t("COMMON.WELCOME", { name: user.value.name });
</script>
```

--------------------------------

### Build Module Package

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/Tutorials-and-How-tos/Tutorials/creating-custom-module.md

Use the Virto Commerce CLI to install the global tool and compress the module into an artifact.

```console
    dotnet tool install VirtoCommerce.GlobalTool -g
    vc-build compress
```

--------------------------------

### Quick Start with useUser

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/user/useUser.md

Demonstrates how to consume user state, authentication status, and loading indicators within a Vue component.

```vue
<script setup lang="ts">
import { useUser } from "@vc-shell/framework";

const { user, isAuthenticated, isAdministrator, loading } = useUser();
</script>

<template>
  <div
    v-if="loading"
    class="tw-animate-pulse"
  >
    Loading user...
  </div>

  <div v-else-if="isAuthenticated">
    <p>Welcome, {{ user?.userName }}</p>
    <span
      v-if="isAdministrator"
      class="tw-badge tw-badge-primary"
      >Admin</span
    >
  </div>

  <div v-else>
    <p>Please sign in to continue.</p>
  </div>
</template>
```

--------------------------------

### Automatic Error Handling Examples

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/custom-apps-development/vc-shell/plugins/global-error-handler.md

Examples of unhandled errors in async functions and Vue components that trigger automatic toast notifications.

```typescript
// This unhandled rejection will trigger a toast notification:
async function loadData() {
  const response = await fetch("/api/orders"); // network error -> toast
  return response.json();
}
```

```typescript
// This Vue component error will also trigger a toast:
const count = computed(() => {
  // TypeError if items is undefined -> caught by Vue errorHandler -> toast
  return items.value.length;
});
```

--------------------------------

### useKeyboardNavigation(options)

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/ui-state/useKeyboardNavigation.md

Initializes keyboard navigation logic for a container of focusable elements.

```APIDOC
## useKeyboardNavigation(options)

### Description
Initializes the keyboard navigation controller. Returns methods to manually attach the navigation to an element and control focus.

### Parameters
- **options** (Object) - Required
  - **itemSelector** (string) - Required: CSS selector for focusable items.
  - **onEnter** (Function) - Optional: Callback triggered on Enter key press.
  - **onEscape** (Function) - Optional: Callback triggered on Escape key press.
  - **loop** (boolean) - Optional: Whether to wrap focus around the list.

### Returns
- **initKeyboardNavigation** (Function) - Method to attach navigation to a specific DOM element.
- **focusFirstElement** (Function) - Method to programmatically focus the first item in the container.
```

--------------------------------

### Use start and end placement variants

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/custom-apps-development/vc-shell/components/feedback/vc-tooltip.md

Align the tooltip to the start or end of the trigger element using specific placement variants.

```vue
<!-- Tooltip appears above, aligned to the left edge of the trigger -->
<VcTooltip placement="top-start">
  <VcButton>Hover me</VcButton>
  <template #tooltip>Aligned to the start</template>
</VcTooltip>
```

--------------------------------

### Call useToolbar within component setup

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/services/useToolbar.md

Ensure useToolbar is called within a component setup function to allow for proper autoCleanup.

```typescript
// Wrong -- no component instance, autoCleanup will not work
function helperFunction() {
  const { registerToolbarItem } = useToolbar();
  registerToolbarItem({ id: "test", title: "Test" });
}

// Correct -- call in <script setup> or within setup(), or pass autoCleanup: false
```

--------------------------------

### Registering a theme on module install

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/ui-state/useTheme.md

Use the register method from useTheme within a module's install function to define available themes.

```typescript
// my-module/index.ts
import type { App } from "vue";
import { useTheme } from "@vc-shell/framework";

export default {
  install(app: App) {
    const { register } = useTheme();

    register([
      { key: "ocean", localizationKey: "MY_MODULE.THEMES.OCEAN" },
      { key: "forest", localizationKey: "MY_MODULE.THEMES.FOREST" },
    ]);
  },
};
```

--------------------------------

### Configure PostgreSQL in appsettings.json

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/Fundamentals/Persistence/DB-Agnostic/configuring-vc-with-db-providers.md

Set the DatabaseProvider to PostgreSql and provide the connection string with host, port, and database credentials.

```json
"DatabaseProvider": "PostgreSql",
"ConnectionStrings": {
"VirtoCommerce": "User ID=postgres;Password=password;Host=localhost;Port=5432;Database=virtocommerce3;"
},
```

--------------------------------

### Initiate SonarQube analysis with SonarQubeStart

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/CLI-tools/build-automation.md

Starts a SonarQube session using the dotnet sonarscanner. Requires authentication token and repository details.

```console
vc-build SonarQubeStart -SonarBranchName dev -SonarAuthToken *** -RepoName vc-module-marketing
```

--------------------------------

### Register menu items during module installation

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/services/useMenuService.md

Use the standalone addMenuItem function during module plugin installation to register items before the component tree mounts.

```typescript
// modules/orders/index.ts
import { addMenuItem } from "@vc-shell/framework";

export default {
  install(app) {
    addMenuItem({
      title: "Orders",
      icon: "fas fa-shopping-cart",
      routeId: "OrdersList",
      priority: 10,
    });

    addMenuItem({
      title: "Returns",
      icon: "fas fa-undo",
      routeId: "ReturnsList",
      priority: 20,
    });
  },
};
```

--------------------------------

### Initialize Serilog in Platform

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/Fundamentals/Logging/extended-logging.md

Configures Serilog by reading from appsettings.json and applying custom ILoggerConfigurationService implementations.

```json
UseSerilog((context, services, loggerConfiguration)
{
    // read from configuration
    _ = loggerConfiguration.ReadFrom.Configuration(context.Configuration);
    // enrich configuration from external sources
    var configurationServices = services.GetService<IEnumerable<ILoggerConfigurationService>>();
    foreach (var service in configurationServices)
    {
        service.Configure(loggerConfiguration);
    }
})
```

--------------------------------

### Design a new application from a prompt

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/custom-apps-development/vc-shell/getting-started/generate-app-from-prompt.md

Use this command to initiate the creation of a new application based on a descriptive prompt.

```text
/vc-app design "Build a supplier operations app with products, offers, fulfillment centers, and team management"
```

--------------------------------

### Run Platform via CLI

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/Getting-Started/Installation-Guide/linux.md

Commands to set the ASP.NET Core environment variables and start the platform application.

```console
export ASPNETCORE_URLS="http://+:5000;https://+:5001"
cd vc-platform-3
dotnet VirtoCommerce.Platform.Web.dll
```

--------------------------------

### Install Modules with CLI

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/CLI-tools/more-targets.md

The InstallModules command installs all modules listed in vc-package.json and resolves their dependencies. Specify a custom path for module discovery using the -DiscoveryPath parameter.

```console
vc-build InstallModules
```

```console
vc-build InstallModules -DiscoveryPath ../modules
```

--------------------------------

### Install Virto Commerce locally with PowerShell

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/Getting-Started/quick-start.md

Downloads and executes the VirtoLocal_create_local_files.ps1 script to deploy the full stack including backend, frontend, and supporting services.

```powershell
$installSCript = Invoke-WebRequest -Uri "https://raw.githubusercontent.com/VirtoCommerce/start-local/dev/VirtoLocal_create_local_files.ps1" -UseBasicParsing; Set-Content -Path ".\VirtoLocal_create_local_files.ps1" -Value $installSCript.Content; .\VirtoLocal_create_local_files.ps1
```

--------------------------------

### Navigate to Platform Directory

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/Updating-Virto-Commerce-Based-Project/stable-releases.md

Change the current working directory to the Virto Commerce platform folder.

```console
cd C:\vc-platform-stable
```

--------------------------------

### Opening Blades with useBlade

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/custom-apps-development/vc-shell/components/layout/vc-blade.md

Demonstrates various ways to open blades, including basic navigation, passing options, lifecycle hooks, and workspace initialization.

```ts
const { openBlade } = useBlade();

// Basic
openBlade({ name: "ProductDetails", param: "product-123" });

// With options (not encoded in URL)
openBlade({
  name: "ProductDetails",
  param: "product-123",
  options: { mode: "edit", category: selectedCategory.value },
});

// With lifecycle hooks
openBlade({
  name: "ProductDetails",
  param: item.id,
  onOpen() {
    selectedItemId.value = item.id;
  },
  onClose() {
    selectedItemId.value = undefined;
  },
});

// Open a workspace (replaces entire blade stack)
openBlade({ name: "SettingsWorkspace", isWorkspace: true });
```

--------------------------------

### Other Non-Product Query Examples

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/Fundamentals/Intent-Search/examples.md

Provides examples of various non-product related queries and their corresponding classifications, such as business information, service information, support requests, and order status inquiries.

```text
// Other non-product examples:
"store hours"               → Business information
"shipping policy"           → Service information
"contact customer service"  → Support request
"track my order"           → Order status inquiry
```

--------------------------------

### CLI Synopsis

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/custom-apps-development/vc-shell/reference/cli/create-vc-app.md

Basic usage patterns for the scaffolding CLI.

```bash
npx @vc-shell/create-vc-app [project-name] [options]
npx @vc-shell/create-vc-app add-module <module-name>
```

--------------------------------

### Configure Vitest

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/custom-apps-development/vc-shell/guides/testing-a-module.md

Define the Vitest configuration and setup file.

```ts
import { defineConfig } from "vitest/config";
import vue from "@vitejs/plugin-vue";
import path from "node:path";

export default defineConfig({
  plugins: [vue()],
  test: {
    environment: "jsdom",
    globals: true,
    setupFiles: ["./vitest.setup.ts"],
  },
  resolve: {
    alias: {
      "@": path.resolve(__dirname, "src"),
    },
  },
});
```

```ts
import "@testing-library/jest-dom/vitest";
```

--------------------------------

### Recompile frontend application

Source: https://github.com/virtocommerce/vc-docs/blob/main/platform/developer-guide/docs/Extensibility/cms-integrations/PageBuilder/create-new-block.md

Execute the build command to apply changes to the frontend.

```bash
yarn run build
```
Tokens:
Raw