Upgrade notes

We're trying to keep the upgrade process as easy as it's possible. Unfortunately, sometimes manual code changes are required. Before pulling out the latest version, please take a look at the upgrade notes below:

1.8 -> 1.9

  • Way of creating VS Modules was changed to use factory method instead of explict object creation. Even though the feature is backward compatible we highly encourage all developers to refactor their modules to use new syntax.

The proces of creating new module with factory method and looks like following:

import { createModule } from '@vue-storefront/core/lib/module'

const moduleConfig: VueStorefrontModuleConfig = { 
  // VS module config 

const module = createModule(moduleConfig)
  • @vue-storefront/store package has been depreciated. Just change imports to @vue-storefront/core/store.

1.7 -> 1.8

Full changelog is available here

  • store/types have been moved to new module called core/types.
  • store/lib/search has been moved to core/lib/search.
  • store/lib/multistore.ts has been moved to core/lib/multistore.ts
  • new styles file for form elements
  • removed unused src/themes/default/filters/index.js file - check if you're not using it as well
  • src/themes/default/resource/head.js has been moved to src/themes/default/head.js
  • src/themes/default/index.basic.template.html has been moved to src/themes/default/templates/index.basic.template.html
  • src/themes/default/index.minimal.template.html has been moved to src/themes/default/templates/index.minimal.template.html
  • src/themes/default/index.template.html has been moved to src/themes/default/templates/index.template.html

1.6 -> 1.7

Starting from Vue Storefront 1.7 we've changed the Caching strategy + Offline ready features:

  • by default, the ElasticSearch Queries are executed using GET method - and therefore are cached by Service Worker (config.elasticsearch.queryMethod - set it to POST for the previous behavior and if You're using graphql),
  • by default products and queries cache is set in the LocalStorage with a quota set to 4MB (config.server.elasticCacheQuota). If the storage quota is set, the cache purging is executed each 30s using LRU algorithm. Local Storage is limited to 5MB in most browsers
  • we've added config.server. disableLocalStorageQueriesCache which is set to true by default. When this option is on then we're not storing the ElasticSearch results in local cache - this is due to the fact that results are by default cached in Service Worker cache anyway.
  • module.extend has been changed to extendModule. You can find usage example in src/modules/index.ts.
  • routes, layouts and component, which are not visible at page rendering are now loaded when they are needed
  • Every store manipulation should be done by dispatching actions. Invoke store dispatch on category/mergeSearchOptions when manipulating store.state.category.current_product_query somewhere.
  • here are all changes in default themes

Backward compatibility - to reverse to the 1.0-1.6 behavior please set:

  • set config.server.disableLocalStorageQueriesCache = false,
  • set config.elasticsearch.queryMethod = POST
  • set config.localForage.defaultDrivers.elasticCache = INDEXEDDB

NOTE: The offline mode may not work properly in the development mode (localhost) because of Service Workers + lack of the bundle prefetching (bundles lazy loading).

With 1.7 the number of attribute descriptors that are loaded on the product page is now limited and dynamically adjusted to the fields used in the product. This behaviour shouldn't have any negative impact on Your app, hovewer if You havent used the attribute/list action explicitly based on all attributes loaded by default (up to 1.6) this may cause the problems. You can switch off dynamic loader by setting the config.entities.product.useDynamicAttributeLoader=false. Details: #2137

Dynamic Categories prefetching (#2076). Starting with Vue Storefront 1.7 we've added a configuration option config.entities.category.categoriesDynamicPrefetch (by default set to true). This option switches the way the category tree is being fetched. Previously we were fetching the full categories tree. In some cases it can generate even few MB of payload. Currently with this option in place we're pre-fetching the categories on demand while user is browsing the category tree

NOTE: Since we're no longer generating category.slug client's side - we need to have category.url_key field unique. If Your Magento2 url_keys are unique it will work without any changes. If not - please do use mage2vuestorefront to re-import the categories. There is a new categories importer option --generateUniqueUrlKeys which is set to true by default.

With the new modules architecture available from 1.6 we've updated the payment modules guide. If You've used the custom payment (and basically any other) extensions please make sure You've already ported them to new modules architecture.

1.5 -> 1.6

With 1.6 we've introduced new modular architecture and moved most of theme-specific logic from core to default theme. It's probably the biggest update in VS history and the first step to making future upgrades more and more seamless.

Due to architectural changes core/components and core/store/modules folders were removed and reorganised into modules ( core/modules). In most cases, the components API remained the same (if not we provided an API bridge in core/compatibility/components folder which allows you to benefit from new features without making changes in your theme). It's a good idea to look for imports referring to deleted folders after migration to be sure that we made a full update.

Overall theme upgrade for default theme requires 105 files to be changed but 85% of this changes is just a new import path for core component which makes this update time-consuming but easy to follow and not risky.

Here you can find detailed information (as a upgrade commit with notes) about what needs to be changed in theme to support VS 1.6.

Global changes

  • Notifications are now based on Vuex Store instead of Event Bus. We've also pulled hardcoded notifications from core to theme

Change in every component:




Change in every store:




and make sure you are importing rootStore.

  • Lazy loading for non-SSR routes is now available

You can now use dynamic imports to lazy load non-SSR routes. You can find examples from default theme here

  • Extensions are now rewritten to modules (and extensions system will be deprecated in 1.7).

If you haven't modified any extensions directly you don't need to change anything. If you made such changes you'd probably need to rewrite your extension to a module.

  • Old event bus is moved to the compatibility folder. From now we are trying to create new features without it and slowly depreciate event bus whenever it's possible. It'll be replaced with some enhanced module-based mechanism with event autosuggestion support.

change all @vue-storefront/core/plugins/event-bus imports to @vue-storefront/core/compatibility/plugins/event-bus

Components that were moved or API was changed and the compatibility component was created.

Required action: Change the import path. In case of additional changes click on a component name to see how to update.

Components that were moved from core to theme

Required action: Add moved content and remove core import. In case of additional changes click on a component name to see how to update.


1.4 -> 1.5


New Modules API

With 1.5.0 we've introduced new heavily refactored modules API. We've tried to keep the old theme components backward compatible - so now You can few some "mock" components in the /core/components just referencing to the /modules/<module>/components original. Please read how modules work and are structured to check if it's implies any changes to Your theme. As it may seem like massive changes (lot of files added/removed/renamed) - It should not impact Your custom code.

New Newsletter module

The existing newsletter integration module was pretty chaotic and messy. @filrak has rewritten it from scratch. If You've relied on existing newsletter module logic / events / etc. it could have affected Your code (low probability).

Memory leaks fixed

We've fixed SSR memory leaks with #1882. It should not affect Your custom code - but if You've modified any SSR features please just make sure that everything still works just fine.

1.3 -> 1.4



We've added GraphQL support. Please read more on the GraphQL Action Plan. Starting from this release bodybuilder package is deprecated. You should use SearchQuery internal class that can be used against API and GraphQL endpoints. Read more on how to query data.

SSR - Advanced output + cache

However, this change is not involving any required actions to port the code but please just be aware that we're supporting SSR Cache + dynamic layout changes etc. If You're using modified version of the theme - You can hardly use these without updating themes/YourTheme/App.vue to the new format (check the default theme for details).


We've added the Reviews support, however, Magento2 is still lacking Reviews support in the REST API. To have reviews up and running please add the https://github.com/DivanteLtd/magento2-review-api to Your Magento2 instance.


  1. We moved core functionalities of coupon codes to API modules:

  2. We moved/renamed methods responsible for UI to default theme:

    • addDiscountCoupon - toggle coupon form
    • removeCoupon -> clearCoupon - removing coupon by dispatch removeCoupon API method and toggle coupon form
    • applyCoupon -> setCoupon - submit coupon form by dispatch applyCoupon API method
    • enterCoupon - was removed, because @keyup="enterCoupon" we changed to @keyup.enter="setCoupon"
  3. We moved $emit with notification about appliedCoupon and removedCoupon from vuex store to default theme. Now applyCoupon and removeCoupon returns promise which you can handle by ourself.

  4. We moved VueOfflineMixin and onEscapePress mixins to theme component. Core component is clean from UI stuff now.

  5. We've replaced one method Microcart - cartTotals -> totals


  1. We removed the default assets from core/assets. From now on, we only use the assets from your-theme/assets.


  1. We moved the socialTiles Vuex store from the core to the theme, because it's specific to the theme.


  1. We removed all the theme specific translations for the core.

1.2 -> 1.3


  1. We've removed event emit from client-entry.js with online status information. Instead of this, we are using now vue-offline mixin. #1494
  2. We've removed isOnline variable from Microcart.js, instead of this, we are using now variables from vue-offline mixin. #1494

Upgrade step by step

global.$VS replaced with rootStore and config was moved to rootStore.state.config

To get access to rootStore import it by

import rootStore from '@vue-storefront/core/store'

cms extenstion was renamed to extension-magento2-cms

Import of CmsData must be changed in CustomCmsPage.vue component to:

import CmsData from '@vue-storefront/extension-magento2-cms/components/CmsData'

1.1 -> 1.2 (release notes)

There were no breaking-changes introduced. No special treatment needed 😃

1.0 -> 1.1 (release notes)


Plugins registration simplified

Instead of exporting an object in {theme}/plugins/index.js just use Vue.use(pugin) directly in this file ( docs )

Microcart logic moved to API module (partially)

Starting from the Microcart we are moving most of the logic to core modules along with unit testing them read more.

Changes that happened in Microcart.js core component and Microcart.vue component from default theme

  • closeMicrocart renamed to closeMicrocartExtend
  • items renamed to productsInCart
  • removeFromCartmethod added to core Microcart

theme/app-extend.js removed

It was redundant

{theme}/service-worker-ext.js moved to {theme}/service-worker/index.js

Now it mirrors core/ folder structure which is desired behaviour

vue-storefront-api docker support has been extended

We've added the possibility to run the vue-storefront-api fully in Docker (previously just the Elastic and Redis images were present in the docker-compose.yml. Please read the README.md for more details.

PLEASE NOTE: We've changed the structure of the elasticsearch section of the config files, moving esIndexes to elasticsearch.indices etc. There is an automatic migration that will update Your config files automatically by running: npm run migrate in the vue-storefront-api folder.

Default storage of the shopping carts and user data moved to localStorage

Currently, there is an config option to setup the default local storage configs: https://github.com/DivanteLtd/vue-storefront/blob/271a33fc6e712b978e10b91447b05529b6d04801/config/default.json#L148. If You like the previous behaviour of storing the carts in the indexedDb - please change the config backend to INDEXEDDB.

mage2vuestorefront improvements

However non-breaking changes - lot of improvements have been added to the mage2vuestorefront importer. For example - fixed special_price sync. For such a changes - please update mage2vuestorefront and re-import Your products. We've also added the dynamic on/demand indexing.

New features

We added vue-progressbar to default theme which can be found in App.vue file

1.0RC-3 -> 1.0(release notes)

This is official, stable release of Vue Storefront.

  1. We've renamed the core/components/*.vue -> the core/components/*.js
  2. We've renamed the core/pages/*.vue -> the core/pages/*.js
  3. We've removed corePage and coreComponent helpers and created an es-lint rule to migrate the import statements automatically (with --fix parameter)

You should replace the mixin declarations from the previous version:

import { coreComponent } from '@vue-storefront/core/lib/themes';

export default {
  mixins: [coreComponent('blocks/MyAccount/MyOrders')],


import MyOrders from '@vue-storefront/core/components/blocks/MyAccount/MyOrders';

export default {
  mixins: [MyOrders],
  1. We've added Multistore support. It shouldn't imply any breaking changes to the existing themes / extensions (by default it's just disabled). More info on that: How to setup Multistore mode.

1.0RC-2 -> 1.0RC-3 (release notes)

This release contains three important refactoring efforts:

  1. We've changed the user-account endpoints and added the token-reneval mechanism which is configured by config.users.autoRefreshTokens; if set to true and user token will expire - VS will try to refresh it.

  2. Moreover, we've separated the user-account entpoints - so please copy the following defaults from default.json to Your local.json and set the correct api endpoints:

    "users": {
      "autoRefreshTokens": true,
      "endpoint": "http://localhost:8080/api/user",
      "history_endpoint": "http://localhost:8080/api/user/order-history?token={{token}}",
      "resetPassword_endpoint": "http://localhost:8080/api/user/reset-password",
      "changePassword_endpoint": "http://localhost:8080/api/user/change-password?token={{token}}",
      "login_endpoint": "http://localhost:8080/api/user/login",
      "create_endpoint": "http://localhost:8080/api/user/create",
      "me_endpoint": "http://localhost:8080/api/user/me?token={{token}}",
      "refresh_endpoint": "http://localhost:8080/api/user/refresh"

The endpoints are also set by the yarn installer so You can try to reinstall VS using this command.

  1. We've optimized the performance by limiting the fields loaded each time in JSON objects from the backend. Please review the config/default.json and if some required / used by Your app fields are missing there - please copy the following fragment to the config/local.json and add the required fields:
    "entities": {
      "optimize": true,
      "twoStageCaching": true,
      "category": {
        "includeFields": [ "children_data", "id", "children_count", "sku", "name", "is_active", "parent_id", "level" ]
      "attribute": {
        "includeFields": [ "attribute_code", "id", "entity_type_id", "options", "default_value", "is_user_defined", "frontend_label", "attribute_id", "default_frontend_label", "is_visible_on_front", "is_visible", "is_comparable" ]
      "productList": {
        "includeFields": [ "type_id", "sku", "name", "price", "priceInclTax", "originalPriceInclTax", "id", "image", "sale", "new" ],
        "excludeFields": [ "configurable_children", "description", "configurable_options", "sgn", "tax_class_id" ]
      "productListWithChildren": {
        "includeFields": [ "type_id", "sku", "name", "price", "priceInclTax", "originalPriceInclTax", "id", "image", "sale", "new", "configurable_children.image", "configurable_children.sku", "configurable_children.price", "configurable_children.special_price", "configurable_children.priceInclTax", "configurable_children.specialPriceInclTax", "configurable_children.originalPrice", "configurable_children.originalPriceInclTax", "configurable_children.color", "configurable_children.size" ],
        "excludeFields": [ "description", "sgn", "tax_class_id" ]
      "product": {
        "excludeFields": [ "updated_at", "created_at", "attribute_set_id", "status", "visibility", "tier_prices", "options_container", "url_key", "msrp_display_actual_price_type", "has_options", "stock.manage_stock", "stock.use_config_min_qty", "stock.use_config_notify_stock_qty", "stock.stock_id",  "stock.use_config_backorders", "stock.use_config_enable_qty_inc", "stock.enable_qty_increments", "stock.use_config_manage_stock", "stock.use_config_min_sale_qty", "stock.notify_stock_qty", "stock.use_config_max_sale_qty", "stock.use_config_max_sale_qty", "stock.qty_increments", "small_image"],
        "includeFields": null

If optimize is set to false - it's a fallback to the previous behaviour (getting all fields).

  1. Another cool feature is twoStageCaching enabled by default. It means that for the Category page VS is getting only the minimum number of JSON fields required to display the ProductTiles and shortly after it downloads by the second request the full objects to store them in local cache.

  2. We've tweaked the Service Worker to better cache the app - it sometimes can generate kind of frustration if your home page is now cached in the SW (previously was not). Feel free to use Clear Storage in Your Developers tools 😃

  3. The mage2vuestorefront tool got update and now it's loading the media_gallery with additional media per product. We've also put some MediaGallery component on the product page.

  4. Product and Category pages got refactored - and it's a massive refactoring moving all the logic to the Vuex stores. So If You played with the core - fetchData/loadData functions probably Your code will be affected by this change.

1.0RC -> 1.0RC-2 (release notes)

This release brings some cool new features (Magento 1.x support, Magento 2 external checkout, My Orders, Discount codes) together with some minor refactors.

Unfortunately with the refactors there comes two manual changes that need to be applied to Your custom themes after the update.

Here You can check an example how did we migrated our own default_m1 theme to RC-2.

  1. We've changed ColorButton, SizeButton, PriceButton in the core to ColorSelector, SizeSelector, PriceSelector and added the GenericSelector for all other attribute types. Because of this change, the coreComponent('ColorButton') must be changed to coreComponent('ColorSelector') etc.

  2. We added the Vuex Stores extensibility to the themes. If You're getting the following build error:

ERROR in ./core/store/index.js
Module not found: Error: Can't resolve 'theme/store' in '***/vue-storefront/core/store'

It means, that You need to copy the template store to: <Your custom theme folder>/store.