You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
This repository was archived by the owner on Jan 26, 2024. It is now read-only.
Copy file name to clipboardExpand all lines: PULL_REQUEST_TEMPLATE.md
+1-1Lines changed: 1 addition & 1 deletion
Original file line number
Diff line number
Diff line change
@@ -23,4 +23,4 @@
23
23
24
24
-[ ] I read and followed [contribution rules](https://github.com/DivanteLtd/vue-storefront/blob/master/CONTRIBUTING.md)
25
25
-[ ] I read the [TypeScript Action Plan](https://github.com/DivanteLtd/vue-storefront/blob/master/doc/TypeScript%20Action%20Plan.md) and adjusted my PR according to it
26
-
-[ ] I read about [Vue Storefront Modules](https://github.com/DivanteLtd/vue-storefront/blob/master/doc/api-modules/about-modules.md) and [refactoring plan for them](https://github.com/DivanteLtd/vue-storefront/blob/master/doc/api-modules/refactoring-to-modules.md)
26
+
-[ ] I read about [Vue Storefront Modules](https://github.com/DivanteLtd/vue-storefront/blob/master/doc/api-modules/about-modules.md) and I am aware that every new feature should be a module
Copy file name to clipboardExpand all lines: doc/api-modules/about-modules.md
+113-8Lines changed: 113 additions & 8 deletions
Original file line number
Diff line number
Diff line change
@@ -39,19 +39,124 @@ The purpose is well described in [this discussion](https://github.com/DivanteLtd
39
39
40
40
# How module should look like
41
41
42
-
Module by it's definition should encapsulate all logic required for the feature it represents. You can think about each module as a micro application that exposes it's parts to the outside world (Vue Storefront).
42
+
43
+
# Module config and capabilities
44
+
45
+
Module config is the object that is required to instantiate VS module. The config object you'll provide is later used to extend and hook into different parts of the application (like router, Vuex etc).
46
+
Please use this object as the only part that is responsible for extending Vue Storefront. Otherwise it may stop working after some breaking core updates.
47
+
48
+
Vue Storefront module object with provided config should be exported in `index.ts` entry point. Ideally it should be a named export named the same as modules key.
49
+
50
+
This is how the signature of Vue Storefront Module looks like:
Key is an ID of your module. It's used to identify your module and to set keys in all key-based extendings that module is doing (like creating namespaced store). This key should be unique. You can duplicate the keys of some other modules only if you want to extend them. Modules with the same keys will be merged.
63
+
64
+
#### `store`
65
+
66
+
Extension point for Vuex. It can be provided with vuex module and Vuex plugin object to subscribe for mutations. In case of conflicting module keys they are deep merged in favour of most recent instantiated one.
67
+
68
+
#### `router`
43
69
44
70
Normally module can (but not must) contain following folders:
45
71
46
-
-`components` - components related to this module (eg. Microcart for Cart module)
47
-
-`store` - Vuex store associated to module
48
-
-`helpers` - everything else that is meant to support modules behavior
49
-
-`types` - TypeScript types associated with module
50
-
-`test` - folder with unit tests which is *required* for every new or rewritten module. This folder can be placed outside of the module in 'tests' folder.
51
-
-`extends` - code that you need to include into core files such as client/server entry, app entry, webpack config or service worker. If you need to extend, let's say `client-entry.js`just create a file with the same name and import it in the core `client-entry.js` by invoking files content with `import core/module/module-name/extends/client-entry.js
72
+
#### `beforeRegistration`
73
+
74
+
Function that'll be called before registering the module both on server and client side. You have access to `Vue` and `config` objects inside.
75
+
76
+
#### `afterRegistration`
77
+
78
+
Function that'll be called after registering the module both on server and client side. You have access to `Vue` and `config` objects inside.
52
79
80
+
# Module file structure
53
81
54
-
[*] currently we are using `core/api/module_name` instead of `module/module_name` but it's about to change soon
82
+
Below you can see recommended file structure for VS module. All of the core ones are organised in this way.
83
+
Try to have similar file structure inside the ones that you create. If all of modules will implement similar architeture it'll be easier to maintain and understand them. If there is no purpose in organising some of it's parts differently try to avoid it.
84
+
85
+
Not all of this folders and files needs to be in every module. The only mandatory file is `index.ts` which is the entry point. The rest depends on your needs and module functionality.
86
+
87
+
-`components` - Components logic related to this module (eg. Microcart for Cart module). Normally it contains `.ts` files but you can also create `.vue` files and provide some baseline markup if it is required for the compoennt to work out of the box.
88
+
-`pages` - If you want to provide full pages with your module palce them here. It's also a good practice to extend router configuration for this pages
89
+
-`store` - Vuex Module associated to this module
90
+
-`index.ts` - Entry point and main export of your Vuex Module. Ations/getters/mutations can be splitted into different files if logic is too complex to keep it in one file. Should be used in `store` config property.
91
+
-`mutation-types.ts` - Mutation strings represented by variables to use instead of plain strings
92
+
-`plugins.ts` - Good place to put vuex plugin. Should be used in `store.plugins` config object
93
+
-`types` - TypeScript types associated with module
94
+
-`test` - Folder with unit tests which is *required* for every new or rewritten module.
95
+
-`hooks` - before/after hooks that are called before and after registration of module.
96
+
-`beforeRegistration.ts` - Should be used in `beforeRegistration` config property.
97
+
-`bafterRegistration.ts` - Should be used in `afterRegistration` config property.
98
+
-`router` - routes and navigation guards associated to this module
99
+
-`routes.ts`- array of route objects that will be added to current router configuration. Should be used in `router.routes` config property.
100
+
-`beforeEach.ts` - beforEeach navigation guard. Should be used in `router.beforeEach` config property.
101
+
-`afterEach.ts`- afterEach navigation guard. Should be used in `router.afterEach` config property.
102
+
-`queries` - GraphQL queries
103
+
-`helpers` - everything else that is meant to support modules behavior
104
+
-`index.js` - entry point for the module. Should export VueStorefrontModule. It's also a good palce to instantiate cache storage.
105
+
106
+
# Rules and good practices
107
+
108
+
First take a look at module template. It cointains great examples, good practices and explainations for everything that can be putted in module.
109
+
110
+
1.**Try not to rely on any other data sources than `config`**. Use other stores only if it's the only way to achieve some functionality and import `rootStore` for this purposes. Modules should be standalone and rely only on themeselves
111
+
2. Place all reusable features as a Vuex actions (e.g. `addToCart(product)`, `subscribeNewsletter()` etc) instead of placing them in components. try to use getters for modified or filtered values from state. We are trying to place most of the logic in Vuex stores to allow easier core updates. Here is a good example of such externalisation.
4. If you want to inform about success/failure of core component's method you can eaither use a callback or scoped event. Omit Promises if you thing that function can be called from the template and you'll need the resolved value. This is a good example of method that you can call either on `template` ot `script` section:
144
+
````js
145
+
addToCart(product, success, failure) {
146
+
this.$store.dispatch('cart/addToCart').then(res=>
147
+
success(res)
148
+
).catch(err=>
149
+
failure(err)
150
+
)
151
+
}
152
+
````
153
+
154
+
Try to choose method basing on use case. [This](https://github.com/DivanteLtd/vue-storefront/blob/develop/core/modules/mailchimp/components/Subscribe.ts#L28) is a good example of using callbacks.
155
+
156
+
5. Create pure functions that can be easly called with different argument. Rely on `data` properties instead of arguments only if it's required (for example they are validated like [here](https://github.com/DivanteLtd/vue-storefront/blob/develop/core/modules/mailchimp/components/Subscribe.ts#L28).
157
+
6. Document exported compoennts like in example: https://github.com/DivanteLtd/vue-storefront/blob/develop/core/modules/mailchimp/components/Subscribe.ts
158
+
7. If your module core functionality is an integration with external service better name it the same as this service (for example `mailchimp`)
The cart module as name suggests is a set of mixins responsible for interacting with Cart. You can find methods responsible for adding/removing/getting cart items along with optional UI interactions for microcart.
Copy file name to clipboardExpand all lines: docs/guide/installation/windows.md
+2Lines changed: 2 additions & 0 deletions
Original file line number
Diff line number
Diff line change
@@ -39,6 +39,8 @@ docker-compose up
39
39
40
40
This step can take some minutes.
41
41
42
+
Note: If it appears that docker-compose is hanging, try opening a new terminal and continue to the next step using that terminal. Allow docker-compose to continue running in the background.
43
+
42
44
6. Restore products database and run latest migrations
0 commit comments