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.
Prerequisites
- 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-app
scaffolding tool using one of the following commands: -
Configure the options based on your requirements. If you are unsure about an option, simply choose
No
by hitting Enter:✔ Project name: … *your-app-name* ✔ Base path: … /apps/*your-app-name*/ ? Select module variant: › - Use arrow-keys. Return to submit. ❯ Dynamic view modules boilerplate Classic view modules boilerplate Module name: › *your-module-name* ? Do you want to include additional module with sample data? › (y/N) Scaffolding app in /*your-app-name*... Done. You can now run application: cd vc-app yarn yarn serve
-
Once the application is created, go to the application folder and add Platform URL to the
.env.local
file under theAPP_PLATFORM_URL
variable: -
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.
Note
The example components in the generated application are written using the Vue Composition API and <script setup>
.
Tip
For an optimal development experience, we recommend using Visual Studio Code with the Volar extension.
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.
├─ src
│ ├─ 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.
Folder | Description |
---|---|
Components | 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. |
Composables | 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. |
Locales | 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 |
Pages | A set of Blades used within application router. |
Create 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 new module in 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 pages
, locales
, and, if necessary, notificationTemplates
as arguments:
With these steps, your module is now ready for use within your application!