Skip to content
Last update: January 27, 2025

Deployment

This section provides detailed instructions on how to deploy the new Virto Commerce Frontend Application across various environments. The deployment options available are:

Deployment on Virto Cloud

Virto Cloud natively supports the new architecture. Use the following methods to deploy in Virto Cloud:

Through configuration file

To deploy through configuration files:

  1. Disable the storefront application by removing it from the configuration.
  2. Add a reference to the Virto Commerce Frontend Application 2.x.
  3. Enable the routes section. The table below shows the mapping of paths to platform routes. The platform routes handle all requests related to the SPA's core functionality, such as authentication, authorization, file management, and data querying.
Path Description
/xapi A custom API endpoint for interacting with the SPA's backend services.
/files A path for uploading and downloading files from the SPA's storage.
/connect/token A path for requesting and refreshing access tokens for the SPA's users.
/graphql A path for executing GraphQL queries and mutations on the SPA's data.
/revoke/token A path for revoking access tokens for the SPA's users.
/api/files An alternative path for accessing the SPA's file management service.

These routes are integral to ensuring that the SPA operates smoothly and securely, handling everything from user authentication to complex data interactions.

The appropriate snippet of the environments.yml file is as follows:

environments.yml
storefront:
    enabled: false
    imageRepository: virtopaasregistrymain.azurecr.io/vcptcore/storefront
    servicePlan: S1
    imageTag: 6.37.0-master-628b3528
    config:
      DOTNET_USE_POLLING_FILE_WATCHER: true
      ASPNETCORE_FORWARDEDHEADERS_ENABLED: true
      CookieAuthenticationOptions__ExpireTimeSpan: 12:00:00
      SnapshotCollectorConfiguration__IsEnabled: false
      Swagger__UI__Enable: true
      VirtoCommerce__DefaultStore: B2B-store
      VirtoCommerce__Endpoint__Password: store
    themes:
          B2B-store: https://vc3prerelease.blob.core.windows.net/packages/b2b-webservice.zip
ingress: {}
customApps:
    app1:
        enabled: false
    app2:
        enabled: false
routes:
- host: vcptcore-dev-storefront.govirto.com
    root: B2B-store
    paths:
    - path: /xapi
        route: platform
    - path: /files
        route: platform
    - path: /connect/token
        route: platform
    - path: /graphql
        route: platform
    - path: /revoke/token
        route: platform
    - path: /api/files
        route: platform
protectedParameters:
    - platform.image.tag
    - storefront.image.tag
    #- themes.B2B-store
    #- custom.app1.image.tag

Through Virto Cloud portal [In Progress]

The detailed instructions will be provided soon.

Deployment on Azure

To deploy the Frontend Application on Azure:

  1. Create all Azure resources using the Azure button:

    Azure button

  2. Fill in the required values on the Custom deployment page and create Azure resources:

    Required values

  3. After successful deployment, open the Platform and perform initial setup, installing sample data if necessary.

  4. Change the default password for the admin user.
  5. Set the store URL (StoresYour storeStore URL) in the Platform in the form of http://x.x.x.x/:

    Current URL

  6. Use the Azure Application Gateway IP address to access the Frontend part of Virtocommerce solutions.

Your Frontend App has now been successfully deployed on Azure.

Common deployment issues

During the deployment process, various issues can arise that require attention, including:

Azure template validation issue

An Azure template validation error may occur if a resource with the selected name already exists. The error message typically indicates that the name must be modified before proceeding.

Azure template validation issue

This issue can arise because the template uses the App Service Name parameter as a name for other Azure resources, potentially leading to conflicts.

Password issue

Errors may occur if the password entered in the Sql Administrator Password field does not meet complexity requirements.

Password issue

To resolve this, the template must be redeployed with a new, compliant password.

Azure infrastructure issue

The error occurs during the deployment process and has a self-explanatory description.

Infrastructure issue

The problem is usually temporary and cannot be solved by the user. The workaround is to use a new resource group for the deployment.

Deployment on local machine

Deploying on a local machine includes:

  1. Meeting the prerequisites.
  2. Deploying the Frontend Application.

Prerequisites

Before installing the Frontend Application:

  1. Install Platform latest version or connect to an instance of the platform that is already set up and running on a cloud service.
  2. Install Experience API/xAPI modules:
  3. Install the following modules for development (but not in production. This will be changed soon):

  4. Install Node.js v22 (22.10.0 or higher).

  5. Enable corepack (run as administrator on Windows):
corepack enable

If you have installed yarn globally, uninstall it:

  • via npm:

    npm uninstall --global yarn
    
  • or through your operation system installation tools:

    • Control Panel, Chocolatey, or Scoop on Windows.
    • Launchpad, Finder, Homebrew, or MacPorts on macOS.
    • Native package manager such as apt on Linux.

Frontend Application deployment

To deploy the Frontend Application on a local machine:

  1. Clone the repository:

    git clone https://github.com/VirtoCommerce/vc-frontend.git "C:\vc-frontend\"
    
  2. Check yarn version. It should be 4.1.0 or higher (not 1.XX.):

    yarn -v
    
  3. Install dependencies:

    yarn install
    
  4. Build and run with hot reload for development:

    1. Add new .env.local file.
    2. Copy APP_BACKEND_URL from the .env file and set its value to the correct endpoint to Virto Commerce Platform:

      # .env.local file
      APP_BACKEND_URL=https://localhost:5001
      
    3. Run yarn dev or yarn dev-expose:

      yarn dev

    4. Follow the link provided in the terminal.

Your Frontend Application is now running successfully.

Frontend Application running

Build options

Choose the appropriate build command based on your needs:

  • Build for production with validation and minification:

    yarn build
    
  • Build in development mode:

    yarn build:dev
    
  • Build in development mode with change tracking:

    yarn build:watch
    

Types generation

To keep your project aligned with the GraphQL server, you need to generate the necessary types by running the following command:

yarn generate:graphql

This command generates the types.ts file for the Core App and independent modules. Even if independent modules are not installed on the platform, the types can still be generated safely.

Dependency analysis

The following sections guide you through analyzing bundle sizes and visualizing the dependency graph.

Bundle size analysis

To optimize your application, it’s important to understand the size of various JavaScript chunks like vendor.js and index.js. Run the following command to analyze bundle sizes:

yarn generate:bundle-map

The results will be saved in the artifacts folder, providing you with a clear overview of your bundle sizes.

Visualize dependency graph

Use the command below to generate a dependency graph:

yarn generate:dependency-graph

Note

This command requires specific parameters to run successfully. For example:

yarn generate:dependency-graph client-app/main.ts client-app/shared/account/components/checkout-default-success-modal.vue

The generated graph will be saved in the artifacts folder for your review.

Localization

Below are the steps to check and fix missing locale keys.

Check for missing locale keys

To ensure that all locale files have consistent keys across different languages and avoid missing translations, run:

yarn check-locales -- path/to/locales_folder path/to/**/locales

The script outputs warnings for any missing keys in the locale files. Review these warnings to ensure all necessary translations are present. This check is also integrated into the CI pipeline to automate the validation process.

Fix missing locales

To automatically fix missing translations in the locale files using AI translation, run.

yarn fix-locales -- path/to/locales_folder path/to/**/locales

This command analyzes all locale files, identifies missing keys, translates the missing content from the source language to the target language, and updates the locale files accordingly.

Note

This command requires the APP_GEMINI_API_KEY environment variable to be set. You can obtain this API key from the Google AI Studio website.

Warning

This is an experimental feature and may not work as expected.

Troubleshooting

If you encounter an error such as dot command not found on Windows, it's likely due to a missing Graphviz installation. Ensure that Graphviz is installed on your system to resolve this issue.