FAQ and Recipes

Below you can find solutions for most common problems and advises for typical config changes required by Vue Storefront. If you solved any new issues by yourself please let us know on slack and we will add them to the list so others don't need to reinvent the wheel.

Problem starting Docker while installing the vue-storefront

In case you get the following error:

│ ERROR                                                                      │
│                                                                            │
│ Can't start Docker in background.                                          │
│                                                                            │
│ Please check log file for details: /tmp/vue-storefront/var/log/install.log │

Please check:

  • if there is docker-compose command available, if not please do install it;
  • please check the output of running docker-compose up -d manually inside the vue-storefront-api instance. On some production environments docker is limited for the superusers, in many cases it's just a matter of /var/run/docker.sock permissions to be changed (for example to 755)

Product not displayed (illegal_argument_exception)

In a case of

  "root_cause": [
      "type": "illegal_argument_exception",
      "reason": "Fielddata is disabled on text fields by default. Set fielddata=true on [created_at] in order to load fielddata in memory by uninverting the inverted index. Note that this can however use significant memory. Alternatively use a keyword field instead."
  "type": "search_phase_execution_exception",
  "reason": "all shards failed",
  "phase": "query",
  "grouped": true,
  "failed_shards": [
      "shard": 0,
      "index": "vue_storefront_catalog_1521776807",
      "node": "xIOeZW2lTwaprGXh6YLyCA",
      "reason": {
        "type": "illegal_argument_exception",
        "reason": "Fielddata is disabled on text fields by default. Set fielddata=true on [created_at] in order to load fielddata in memory by uninverting the inverted index. Note that this can however use significant memory. Alternatively use a keyword field instead."

See the discussion in #137. Please also check the Database tool

One of the options is to do kind of fork - or just to get the whole repo to your Git service. Then if you like to do some VS updates you probably need to just pull the changes from our origins. Another option will be available as soon as we manage to separate the core as an npm module

How to add custom configurable attributes to the Product page

Where can we add filters and extra configurable options for the products? For example, I've just added an iPhone X as an example. And I want to add the storage as an option.

How to add additional custom attribute?

To do so, you need to modify the theme, changing the following snippet:

<div class="row top-xs m0 pt15 pb40 variants-wrapper">
  <div v-if="option.label == 'Color'">
      v-for="(c, i) in options.color"
      :class="{ active: c.id == configuration.color.id }"
  <div class="sizes" v-if="option.label == 'Size'">
      v-for="(s, i) in options.size"
      class="mr10 mb10"
      :class="{ active: s.id == configuration.size.id }"

You must add UI controls for additional configurable attributes.

Product name changed to SKU when adding to cart / on the product page

By default, when the user selects any specific product variant on the Product.vue page for configurable products - the title, picture, price and other attributes are changed to corresponding simple one (within product.configurable_children). If in the Magento panel the product names of the variants are set to SKU or anything else, then the correct behavior is that the product name change to it when selects variant.

To correct this behavior you can:

  • modify the core - to filter out the name attribute from Object.assign which is responsible for copying the attributes from variant -> current product,
  • modify mage2vuestorefront importer to correct the configurable_children product names
  • or just use bound to the EventBus.$emitFilter('product-after-single', { key: key, options: options, product: products[0] }) event and modify the product.configurable_children properties:
  if (product.configurable_children) {
    for (let configurableChild of product.configurable_children) {
        configurableChild.name = product.name

How to get dynamic prices to work (catalog rules)

After following the Tutorial on how to connect to Magento2 the prices are updated just after manually running mage2vuestorefront cli command.

However, there is an option to get the prices dynamically. To do so you must change the config inside conf/local.json from the default (conf/default.json):

  "products": {
    "preventConfigurableChildrenDirectAccess": true,
    "alwaysSyncPlatformPricesOver": false,
    "clearPricesBeforePlatformSync": false,
    "waitForPlatformSync": false,
    "endpoint": "http://localhost:8080/api/product"


  "products": {
    "preventConfigurableChildrenDirectAccess": true,
    "alwaysSyncPlatformPricesOver": true,
    "clearPricesBeforePlatformSync": true,
    "waitForPlatformSync": false,
    "endpoint": "http://localhost:8080/api/product"

To make it work you need have Magento2 Oauth keys configured in your vue-storefront-api - conf/local.json. This change means that each time the product list will be displayed, VS will get fresh prices directly from Magento without the need to re-index ElasticSearch.

No products found! after node --harmony cli.js fullreindex

Take a look at the discussion at #644 Long story short -> you need to run the following command within the mage2nosql project:

node cli.js products --partitions=1

How to sync the products cart with Magento to get the Cart Promo Rules up and running

To display the proper prices and totals after Magento calculates all the discounts and taxes you need to modify the conf/local.json config (for a reference take a look at conf/default.json) by putting there an additional section:

  "cart": {
    "synchronize": true,
    "synchronize_totals": true,
    "create_endpoint": "http://localhost:8080/api/cart/create?token={{token}}",
    "updateitem_endpoint": "http://localhost:8080/api/cart/update?token={{token}}&cartId={{cartId}}",
    "deleteitem_endpoint": "http://localhost:8080/api/cart/delete?token={{token}}&cartId={{cartId}}",
    "pull_endpoint": "http://localhost:8080/api/cart/pull?token={{token}}&cartId={{cartId}}",
    "totals_endpoint": "http://localhost:8080/api/cart/totals?token={{token}}&cartId={{cartId}}"

To make it work you need have Magento2 oauth keys configured in your vue-storefront-api - conf/local.json.

After this change, you need to restart the yarn dev command to take the config changes into consideration by the VS. All the cart actions (add to cart, remove from cart, modify the qty) are now synchronized directly with Magento2 - for both: guest and logged in clients.

How to prevent an error "Can’t build storefront npm"

The error "Can't build storefront npm" appears because npm can't automatically install required modules. To prevent this error, you should manually install those modules before running the installer. It's easy:

git clone https://github.com/DivanteLtd/vue-storefront.git vue-storefront && cd vue-storefront
npm install
npm install vue-carousel vue-no-ssr
npm run build # check if no errors
npm run installer

How to integrate 3rd party platform? Do you think it could be used with a legacy bespoke PHP eCommerce?

Yes, I believe it could. You should expose the API accordingly to our spec and the second step is to create a data bridge to fill out the ElasticSearch with the current catalog data.

Is there any documentation on integrating payment gateways?

We're working on kind of boilerplate for payment modules. Right now please just take a look at a live example and try to follow the design patterns from there. The task where boilerplate + docs will show up is https://github.com/DivanteLtd/vue-storefront/issues/923.

Is there any internationalization support?

Yes, we already have 7 languages supported by default (EN, FR, ES, RU, JP, NL, DE) and the documentation for translations.

The currency is set in the local.json configuration file and it's (along with the language) set per instance - so if you have a few languages and countries supported you need to run (as for now) a few separate instances

If 10k products are on the site will it create a high bandwidth download when you navigate on the site for the first time on a mobile device

Not necessarily. Vue Storefront is caching products from the categories browsed. This is the default solution which can be changed by modifying core/store/lib/search.js

How to add/remove/change field types in the ElasticSearch schema

It's done via Database Tool schema changes. Please follow the instructions from the Database Tool Manual.

How to integrate 3rd party Magento extensions

Unfortunately, Magento extensions are not compliant with any PWA available solution yet. So if you would like to integrate some existing extensions, the simplest way is to:

  • expose the data via some Magento2 REST api endpoints;
  • consume the endpoints in the VS using Vuex stores; read more about Vuex in Vue Storefront;
  • implement the UI in VS

If the extensions are not playing with the User Interface, probably they will work with VS out of the box, as we're using the standard Magento2 API calls for the integration part.

How to support Multistore / Multi website setup

Please check the Multistore setup guide for details

How to deal with Category filters based on configurable_children

If you would like to have a Category filter working with configurable products, you need to expand the product.configurable_children.attrName to product.attrName_options array. This is automatically done by mage2vuestorefront for all attributes set as product.configurable_options (by default: color, size). If you like to add additional fields like manufacturer to the filters, you need to expand product.manufacturer_options field. The easiest way to do so is to set config.product.expandConfigurableFilters to ['manufacturer'] and re-run the mage2vuestorefront indexer.

How to redirect original Magento2 URLs to Vue Storefront

There is an SEO redirects generator for NGINX -> https://serverfault.com/a/441517 available within the vue-storefront-api. Now you can generate SEO map redirecting users from the original Magento URLs to Vue Storefront URLs by running:

npm run seo redirects — —oldFormat=true | false
  • oldFormat - should be set accordingly to the vue-storefront/config/local.json setting of products.useShortCatalogUrls (oldFormat = !useShortCatalogUrls)

Please make sure that vue-storefront/config/local.json setting of useMagentoUrlKeys is set to true and you have ElasticSearch synchronized with the Magento2 instance using the current version of mage2vuestorefront.

Please note: As url_key field must be unique across categories collection. Therefore - we're by default generating its value based on name + category id. Please switch this option off if You'd like to keep the url_key as they come from Magento2.

You need to choose options for your item message when hit API for add to cart a configurable product

This is because the demo data dump works on the demo-magento2.vuestorefront.io instance attribute ids. Please re-import all product data using mage2vuestorefront

Adding custom category filters

You need to add the attributes you'll like to have displayed to the config/local.json field name is: products.defaultFilters:

"defaultFilters": ["color", "size", "price", "erin_recommends"],

And then You can use proper controls for each individual filter here.

Collecting all VSF i18n phrases into a CSV.

It might be very time consuming to translate the whole project into a foreign language. A good start is to properly collect all i18n phrases into a CSV file. The following line of bash code would get the job done (a pipe-separated CSV file named i18n.csv would be created, adjust accordingly to your needs).

Execute the following line on your project's root folder:

grep --include \*.js --include \*.vue -nrw ./ -e 'i18n.t(' -e '$t(' -h | grep -o -P "(?<=t\(\').*(?=\'\))" | awk -F"'" -v OFS='|' '{ print $1,$1 }' > i18n.csv

The code basically looks into all project files for all i18n.t('some string') and $t('some string') occurrences, parses an extracts the quoted text of each occurrence, and saves it into a pipe-separated CSV file, which you might help you to get your missing translations.