Create first VC-Shell application¶
In this section we will show you how to scaffold a VC Shell application on your local machine. The created project will use Vue 3 and Vite as the build setup.
- You have an up-to-date installation of Node.js.
- Your current working directory is set to the location where you want to create the application.
To create and install custom app:
Install and run the
create-vc-appscaffolding tool using one of the following commands:
Configure the options based on your requirements. If you are unsure about an option, simply choose
Noby hitting Enter::
Once the application is created, go to the application folder and add Platform URL to the
.envfile under the
Go to the
definekey from the config to activate API calls to the Platform.
Go to the
src/main.tsand uncomment commented code with
loadUsermethod, which is said to be removed after adding
Install the dependencies and start the development server:
Your first VC-Shell application is now ready to run!
An example application with classic and dynamic views, created using
@vc-shell/create-vc-app package, can be found in the
sample/vc-app folder in the VirtoCommerce/vc-shell github repo.
The example components in the generated application are written using the Vue Composition API and
Application folder structure¶
After the application is scaffolded, the folder structure will look as follows:
├─ public // Static assets
│ ├─ assets // Static images used inside the application.
│ └─ img
│ └─ icons // Icons used for favicons, PWA, etc.
│ ├─ api_client // Generated API clients folder
│ │ └─...
│ ├─ composables // Application composables
│ │ └─...
│ ├─ locales // Locale files used to provide translated content
│ │ └─ en.json
│ ├─ modules // The collection of custom modules
│ │ └─ ... // Modules folder
│ │ ├─ components // The collection of components specific for this module
│ │ │ ├─ notifications // Dropdown notifications templates
│ │ │ └─ ...
│ │ ├─ composables // The collection of shared logic written using Composable API pattern.
│ │ ├─ locales // Locale files used to provide translated content specific for this module
│ │ ├─ pages // Set of module pages used within Application router
│ │ └─ index.ts // Module entry point
│ ├─ pages // Set of application pages used within Application router.
│ │ └─...
│ ├─ router // SPA routing configuration
│ │ └─...
│ ├─ styles // Extras application style files
│ │ └─ index.scss // Tailwind initialization file
│ └─ types // Typescript .d.ts files
Let's take a look at the modules directory as it represents the key concept in the application's architecture.
Modules directory structure¶
A module is a collection of composables, locales, components, and pages. Each module is responsible for its own functionality and can contain the number of blades you need to serve your specific requirements, which are stored in the "pages" folder. A blade is a standalone page with its own functionality and template.
Blades are not interconnected, but they can be used together using special methods.
|This directory contains components that are specific to this module. If you want to create a component for your module, the components folder is the ideal place to do so. Components placed within a module should only be used within that module. If a component needs to be used globally, it's better to place it in the components folder at the root of the application.the application root folder.
|The collection of shared logic written using Composable API pattern.
It may include, for example, logic for loading data from the backend which is used by blade.
|The folder stores locale files used to provide translated content specific to the module. If you need to translate your blades into multiple languages, you can store all the translations in JSON format in this folder. These translations can then be processed using the vue-i18n library.
Syntax of localization files
|A set of Blades used within application router.
Create a new module¶
To create your own modules within the scaffolded application folder structure:
Create a new folder for your module inside the src/modules directory. Choose a descriptive name that reflects its functionality. You can create multiple modules within the src/modules directory, with each module responsible for a specific set of features or pages.
Inside your module folder, organize your module-specific code into different directories as needed.
Additionally, you can include an index.ts file as the entry point for your module. This file can provide the necessary exports and configurations for your module.
Initialize a new module in the application¶
Initialize your module to make it usable within the application.
All modules are created as Vue plugins. To simplify the module installation process, you can initialize it using the
createAppModule method. This method takes
locales, and, if necessary,
notificationTemplates as arguments:
With these steps, your module is now ready for use within your application!