{"id":20604582,"url":"https://github.com/virtocommerce/vc-frontend","last_synced_at":"2026-02-09T16:16:43.712Z","repository":{"id":36979781,"uuid":"296335982","full_name":"VirtoCommerce/vc-frontend","owner":"VirtoCommerce","description":"Virto Commerce Frontend - B2B SPA is a fresh look on the field of eCommerce solutions. This is a place where common B2B and B2C scenarios are combined with the most bleeding edge technologies to deliver blazing fast and fully functional solution. It implements common business use-cases needed for a vast majority of projects we build.","archived":false,"fork":false,"pushed_at":"2024-10-29T09:18:57.000Z","size":34283,"stargazers_count":37,"open_issues_count":18,"forks_count":31,"subscribers_count":19,"default_branch":"dev","last_synced_at":"2024-10-29T09:19:21.300Z","etag":null,"topics":["ecommerce","graphql","pwa-app","spa","typescript","virtocommerce","vue3"],"latest_commit_sha":null,"homepage":"https://virtostart-demo-store.govirto.com/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/VirtoCommerce.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-09-17T13:32:49.000Z","updated_at":"2024-10-28T12:41:37.000Z","dependencies_parsed_at":"2023-10-16T11:46:15.588Z","dependency_job_id":"11c9e8e7-50f5-4bc0-bf88-ca1ce6ed7c44","html_url":"https://github.com/VirtoCommerce/vc-frontend","commit_stats":null,"previous_names":["virtocommerce/vc-frontend"],"tags_count":72,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VirtoCommerce%2Fvc-frontend","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VirtoCommerce%2Fvc-frontend/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VirtoCommerce%2Fvc-frontend/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VirtoCommerce%2Fvc-frontend/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/VirtoCommerce","download_url":"https://codeload.github.com/VirtoCommerce/vc-frontend/tar.gz/refs/heads/dev","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247713258,"owners_count":20983683,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ecommerce","graphql","pwa-app","spa","typescript","virtocommerce","vue3"],"created_at":"2024-11-16T09:23:49.285Z","updated_at":"2026-02-09T16:16:43.706Z","avatar_url":"https://github.com/VirtoCommerce.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![stage](https://img.shields.io/badge/Stage-EDGE-blue)](https://virtocommerce.atlassian.net/wiki/spaces/DE/pages/2329018420/Classification) ![ci](https://github.com/VirtoCommerce/vc-theme-b2b-vue/actions/workflows/theme-ci.yml/badge.svg) ![size](https://img.shields.io/github/repo-size/VirtoCommerce/vue-starter-theme) ![version](https://img.shields.io/github/package-json/v/VirtoCommerce/vue-starter-theme) ![discord](https://img.shields.io/discord/932283445596553228)\n\n# Virto Commerce Frontend\n\n\u003cimg src=\"demo.jpg\" width=\"800\" alt=\"catalog view\"\u003e\n\n**Virto Commerce Frontend** is a single-page web application (SPA) with a fresh look on eCommerce solutions. This is where common B2B and B2C scenarios are combined with the most bleeding-edge technologies to deliver blazing-fast and fully functional solutions. It implements common business use cases needed for a vast majority of projects we build.\n\nVirto Commerce Frontend is designed to be used as-is within the actual **Virto Commerce Platform**. You can modify it by implementing desired components, pages, and shared logic to correspond with your project goals.\n\n## Technologies used\n\n- **Vue3.** Progressive frontend framework with its key features allows to build fast applications.\n- **Typescript.** All components and composables have type definitions, so IDE can help you to build clean and working code.\n- **TailwindCSS.** The most popular and growing CSS framework provides a wonderful flexible structure to speed up styling.\n- **Husky + ESLint + Prettier.** Autoformat, check and fix your code and prevent ugly code style within the repository.\n- **Vite.** It is faster than Webpack. Really FASTER. Use it to develop with HMR benefits and to build for production.\n- **GraphQL.** Forget about REST, use flexible GraphQL queries and mutations to safely work with the backend.\n\n## Non-functional key features\n\n- **Development performance.** Really fast development using the most effective solution. Enrol SPA in seconds and start to modify code with [HMR features](https://vitejs.dev/guide/api-hmr).\n- **Client performance.** We are supposed to reach and hold green metrics provided by Google PageSpeed Insights.\n- **[Atomic Design Pattern.](https://virtocommerce.com/atomic-architecture)** The Frontend Application UI is based on Atoms, Molecules and Organisms, combined within Pages and shared Components. This provides a high level of code reusability.\n- **Fully responsive.** We made our Frontend Application work on multiple devices from Desktops to Mobile phones, concentrating both on UI and UX.\n- **Simple styling and customization.** We use TailwindCSS to provide the easiest and most convenient way of CSS usage. Write as less of code as possible, and reuse existing highly customizable framework features.\n- **Fully aligned with Virto Commerce Platform.** The SPA is fully aligned with the [Virto Commerce Platform](https://github.com/VirtoCommerce/vc-platform) to provide all common B2B and B2C scenarios. \n\n## The Application structure\n\n```text\n├── assets                           // Scripts, styles and other assets compiled and minified for production.\n|\n├── client-app                       // The main folder for the application.\n|   ├── assets                       // Assets needed to be precompiled during building.\n|   |   └──...\n|   |\n|   ├── core                         // Common utilities and shared logic that can be used by any pages and libraries.\n|   |   ├── api/graphql              // GraphQL Models aligned with the Virto Backoffice.\n|   |   |   └──...\n|   |   ├── composables              // Core composables (app-level shared logic).\n|   |   |   └──...\n|   |   ├── directives               // Core Vue directives.\n|   |   |   └──...\n|   |   ├── plugins                  // Core Vue plugins.\n|   |   |   └──...\n|   |   ├── enums                    // Core enums.\n|   |   |   └──...\n|   |   ├── types                    // Core types.\n|   |   |   └──...\n|   |   ├── utilities                // Some miscellaneous utils.\n|   |   |   └──...\n|   |   └── constants.ts             // Global-available constants (DO NOT USE, will be removed later).\n|   |\n|   ├── pages                        // Set of application pages used within Application router.\n|   |   └──...\n|   |\n|   ├── public                       // Statically served files\n|   |   └── static\n|   |       ├── icons                // Icons used for favicons, PWA, etc.\n|   |       └── images               // Static images used inside the application.\n|   |\n|   ├── router                       // SPA routing configuration.\n|   |   └──...\n|   |\n|   ├── shared                       // A set of shared files grouped by their domain context.\n|   |   ├── catalog                  // Grouping context (ex.: catalog browsing).\n|   |   |   ├── components           // The collection of components specific for this domain context.\n|   |   |   |   └──...\n|   |   |   ├── composables          // The collection of shared logic written using Composable API pattern.\n|   |   |   |   └──...\n|   |   |   ├── types                // Types used in this context.\n|   |   |   |   └──...\n|   |   |   ├── utils                // Utilities and helpers specific for this context.\n|   |   |   |   └──...\n|   |   |   └── index.ts             // Entry point for this context used as library.\n|   |   |\n|   |   └──...\n|   |\n|   ├── ui-kit                       // Atoms, Molecules, Organisms and their types, used within the whole application.\n|   |   └──...\n|   |\n|   ├── App.vue                      // Main Application component. Use it as a wrapper for routable pages.\n|   ├── env.d.ts                     // Definition file to provide IDE IntelliSense support.\n|   ├── main.ts                      // Application entry point. Main initialization script.\n|   ├── shims-acceptjs.d.ts          // Definition file to provide IDE IntelliSense support for Accept.js (Authorize.net).\n|   ├── shims-graphql.d.ts           // Definition file to provide IDE IntelliSense support for importing *.graphql files.\n|   ├── shims-vue.d.ts               // Definition file to provide IDE IntelliSense support for importing *.vue files.\n|   ├── vue.d.ts                     // Definition file to provide IDE IntelliSense support for additional global Vue properties.\n|   └── vue-router.d.ts              // Definition file to provide IDE IntelliSense support for additional global Vue Router properties.\n|\n├── config\n|   ├── menu.json\n|   └── settings_data.json\n|\n├── examples                         // Code snippets and examples for different use cases.\n|   \n├── locales                          // Locale files used to provide translated content.\n|   └──...\n|\n├── modules                          // Modules with their own components, APIs, and logic.\n|   └──...\n|\n├── scripts                          // Auxiliary build files that run in the Node environment.\n|   └──...\n|\n├── .babelrc                         // Babel configuration for storybook\n├── .browserslistrc                  // Browserslist config file to support actual versions of browsers.\n├── .commitlintrc.json               // Config for Conventional commit hook.\n├── .dependency-cruiser.cjs\n├── .dependency-graph.cjs\n├── .editorconfig                    // Common editor settings to sync codestyle.\n├── .env                             // Envfile to define different Environment Variables.\n├── .env.local                       // Local envfile to override Environment Variables.\n├── .gitattributes                   // Set attributes to specified path in Git.\n├── .gitignore                       // Ignore some files from Git.\n├── .npmrc                           // Node.js package manager settings and Node.js restrictions\n├── .prettierignore                  // Ignore some files from Prettier.\n├── .prettierrc.json                 // Config for Prettier.\n├── .yarnrc.yml                      // Yarn package manager configuration\n├── eslint.config.js                 // ESlint configuration file.\n├── graphql-codegen\n|   └── generator.ts                 // Generate GraphQL types \n├── index.html                       // Vite Development entry point.\n├── LICENSE.txt\n├── package.json                     // NPM Package description.\n├── postcss.config.cjs               // PostCSS configuration for Tailwind.\n├── README.md                        // This file.\n├── sonar-project.properties\n├── tailwind.config.ts               // TailwindCSS configuration file.\n├── tsconfig.app.json                // Typescript configuration for application.\n├── tsconfig.json                    // Main TypeScript configuration file.\n├── tsconfig.node.json               // Typescript configuration for Node.js.\n├── tsconfig.vitest.json\n├── vite.config.ts                   // Vite configuration file.\n├── vitest.config.ts\n└── yarn.lock                        // Yarn dependencies lock file.\n```\n\n## Getting started\n\n### Prerequisites\n\n- Install `vc-platform` 3.x the latest version:\n  - [Deploy on Windows](https://github.com/VirtoCommerce/vc-platform/blob/master/docs/getting-started/deploy-from-precompiled-binaries-windows.md)\n  - [Deploy on Linux](https://github.com/VirtoCommerce/vc-platform/blob/master/docs/getting-started/deploy-from-precompiled-binaries-linux.md)\n- Install [Experience API / X-Api](https://github.com/VirtoCommerce/vc-module-experience-api/blob/dev/docs/getting-started.md) modules:\n  - [vc-module-x-api](https://github.com/VirtoCommerce/vc-module-x-api)\n  - [vc-module-profile-experience-api](https://github.com/VirtoCommerce/vc-module-profile-experience-api)\n- The following modules should be installed for development (but not in production; this will be changed in the future):\n  - [vc-module-file-experience-api](https://github.com/VirtoCommerce/vc-module-file-experience-api)\n  - [vc-module-push-messages](https://github.com/VirtoCommerce/vc-module-push-messages)\n  - [vc-module-skyflow](https://github.com/VirtoCommerce/vc-module-skyflow)\n  - [vc-module-x-recommend](https://github.com/VirtoCommerce/vc-module-x-recommend)\n- Install [Node.js v22](https://nodejs.org/en/download/) (**22.12.0** or later)\n- Enable [corepack](https://yarnpkg.com/corepack) *(run as administrator on Windows)*\n  ```bash\n  corepack enable\n  ```\n- If you have installed `yarn` globally, uninstall it:\n  - via `npm`\n    ```bash\n    npm uninstall --global yarn\n    ```\n  - or through your Operation System installation tools\n     - `Control Panel`, `Chocolatey` or `Scoop` on *Windows*\n     - `Launchpad`, `Finder`, `Homebrew` or `MacPorts` on *macOs*\n     - Native package manager such as `apt` on *Linux*\n\n### Clone repository\n```bash\ngit clone https://github.com/VirtoCommerce/vc-frontend.git \"C:\\vc-frontend\\\"\n```\n\n### Check yarn version\n```bash\nyarn -v\n```\n`Yarn` should be of version **4.1.0** or greater, not 1.XX.\n\n### Install dependencies\nUse `--immutable` flag to ensure that the dependencies are installed with the correct version.\n```bash\nyarn install --immutable\n```\n\n### Build\n\n#### Run with hot reload for development\n\n- Add new **.env.local** file\n- Copy **APP_BACKEND_URL** from **.env** file and change it's value to the correct endpoint to `Virto Commerce Platform`:\n\n```dotenv\n# .env.local file\nAPP_BACKEND_URL=[your endpoint, example https://localhost:5001]\n```\n\n- Run command: `yarn dev` or `yarn dev-expose`\n- Follow the link in the terminal\n\n#### Build with validation and minification for production\n\n```bash\nyarn build\n```\n\n#### Build in development mode\n\n```bash\nyarn build:dev\n```\n\n#### Build in development mode with change tracking\n\n```bash\nyarn build:watch\n```\n\n## Types generation\n\nCommand:\n```\nyarn generate:graphql-types\n```\n\nGenerates the `types.ts` files separately for `The Core App` and independent modules.\nIf independent modules are not installed on `The Platform`, types can still be safely generated.\n\n## Dependency Analysis\n\n### Bundle Size Analysis\n\nTo examine the sizes of various chunks such as `vendor.js` or `index.js`, execute the following command:\n```\nyarn generate:bundle-map\n```\nThe results will be located in the `artifacts` folder.\n\n### Visualizing the Dependency Graph\n\nTo create a visual representation of the dependency graph, use the following command:\n```\nyarn generate:dependency-graph\n```\n**Note**: This command requires parameters to run successfully. For example:\n```\nyarn generate:dependency-graph client-app/main.ts client-app/shared/account/components/checkout-default-success-modal.vue\n```\nIf command \"dot\" is missing - install graphviz on your OS\n\nThe generated graph will also be saved in the `artifacts` folder.\n\n## Localization\n### Language Flow\n- Locale selection checks the URL first - using the supported languages list to tell real locale segments from ordinary path parts (full culture like `fr-FR` or an unambiguous short alias such as `fr`), then your “pinned” locale - your last choice saved in localStorage, then your account’s preferred culture, and finally the store default.\n\n- When a locale is chosen, useLanguages.initLocale lazy-loads its translation file (`xx-YY.json`; if missing it falls back to `xx.json`, then to `en.json`), wires it into Vue I18n and Yup, updates the `\u003chtml lang\u003e` tag, and rewrites the URL so default or mismatched locale segments vanish.\n\n- Switching via the header selector stores the new culture, captures the exact slug and culture you were on at that moment (previousCultureSlug in session storage), strips any stale locale prefix from the URL, broadcasts a data refresh, and reloads so the whole app restarts in the new language.\n\n- After that reload, useSlugInfo notices previousCultureSlug; while you stay on the same path it asks the backend for slug data using the recorded culture, so `/hello` is resolved with `en-US` instead of the new `fr-FR`, preventing empty responses before the localized slug is known.\n\n- When product, category, brand, or CMS data brings back a localized permalink (updateLocalizedUrl in those page modules), it uses history.pushState to refresh the browser address with the localized path - keeping locale prefix, query string, and hash - so users see the correct URL without triggering router navigation or extra data fetching.\n\n### Check for missing locale keys\n```\nyarn check-locales --source en.json -- path/to/locales_folder path/to/**/locales\n```\nThe command checks for missing keys in locale files by comparing them against a single source-of-truth file (e.g., `en.json`), specified with the `--source` argument. This ensures that all other language files have the same keys as the source file, helping to maintain consistency and avoid missing translations.\n\nThe script will output warnings for any missing keys in the locale files. Review these warnings to ensure all necessary translations are present. Also added to the CI pipeline.\n\n### Fix Missing Locales\n```\nyarn fix-locales --source en.json -- path/to/locales_folder path/to/**/locales\n```\nThis command automatically fixes missing translations by comparing other locale files against a single source-of-truth file (e.g., `en.json`), specified with the `--source` argument. It identifies missing keys, uses an AI to translate them from the source language, and updates the files accordingly.\n\n\u003e [!IMPORTANT]\n\u003e This command requires the `APP_GEMINI_API_KEY` environment variable to be set. You can obtain this API key from the [Google AI Studio](https://aistudio.google.com/app/apikey) website.\n\nYou can also override the default translation model, temperature, and inter-file request delay via environment variables:\n- `FIX_LOCALES_MODEL_NAME` (default: \"gemini-2.0-flash\")\n- `FIX_LOCALES_TEMPERATURE` (default: 0.0)\n- `FIX_LOCALES_DELAY_MS` (default: 4000)\n\n\u003e [!CAUTION]\n\u003e This is an experimental feature and may not work as expected.\n\n### Styles customization\n\nComponent styles follow the BEM methodology. To avoid merge conflicts and keep your customizations centralized, **do not edit the core style files**. Instead, put all your overrides into the `client-app/assets/styles/_custom.scss` file.\n\n```scss\n// client-app/assets/styles/_custom.scss\n\n.vc-container {\n  \u0026__bg {\n    background-color: red;\n  }\n}\n```\n\n## Configurable Border Radius\n\nYou can easily adjust border-radius values for all components or on a per-component basis using CSS custom properties:\n\n- `--vc-radius`:\n  Sets the **global** border-radius for all components.\n  **Default:** `0.5rem` (8px)\n\n- Per-component overrides:\n  If you need a different radius for a specific component, you can override the global value by defining a custom property scoped to that component. For example:\n  - `--vc-button-radius`\n  - `--vc-widget-radius`\n  - _etc._\n\n- **Recommended** maximum border-radius: 10px (0.625rem). Larger values may appear overly rounded and disrupt visual consistency.\n\n```scss\n// client-app/assets/styles/_custom.scss\n\n:root {\n  // Change the global radius\n  --vc-radius: 0.25rem; // now 4px\n\n  // Override button radius only\n  --vc-button-radius: 0.75rem; // now 12px\n}\n```\n\n### Troubleshooting\n\nIf you encounter an error such as `dot command not found` on Windows, ensure that [Graphviz](https://graphviz.gitlab.io/download/) is installed on your system.\n\n## License\n\nCopyright (c) Virtosoftware Ltd. All rights reserved.\n\nLicensed under the Virto Commerce Open Software License (the \"License\"); you\nmay not use this file except in compliance with the License. You may\nobtain a copy of the License at\n\n[https://virtocommerce.com/opensourcelicense](https://virtocommerce.com/opensourcelicense)\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or\nimplied.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvirtocommerce%2Fvc-frontend","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvirtocommerce%2Fvc-frontend","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvirtocommerce%2Fvc-frontend/lists"}