Here is a short tutorial for developers — on how to connect Vue Storefront to Magento 2 instance and develop your own customizations. It’s probably a good starting point for your first VS based implementation. So, let’s get started!

Intro to VSF installation on Magento 2

To get started with VS we must start with some very basics about the architecture; the project is backed by three separate Node.js applications

Vue Storefront Architecture

vue-storefront (Github) — is the main project where you can also find most of the documentation, issues mapped to further releases and other resources to start with — Vue.js on webpack.

vue-storefront-api (Github) — is the API layer which provides the data to vue-storefront app — Node.js, Express; This project consists of docker instances for Redis and ElasticSearch required by mage2vuestorefront and pimcore2vuestorefront

mage2vuestorefront (Github)or pimcore2vuestorefront (Github) — data bridges that are in charge of moving data back from Magento 2 or Pimcore to Vue Storefront data store.

The project doesn’t use Magento nor Pimcore database directly. We store all Products, Categories, TaxRules, Attributes in Elastic Search database which is used by vue-storefront-api. This is a very important assumption you must keep in mind while developing your custom code.


Vue Storefront is well tested on MacOS and Linux platforms. Although you can develop frontend customizations (vue-storefront project) on your Windows machine, vue-storefront-api and mage2vuestorefront are not fully supported by this OS.


To complete this tutorial, you need to have:


To get started — first of all, we need to install all projects on your local machine. Fortunately, it’s a very simple step because we do have CLI installer which installs vue-storefront and vue-storefront-api altogether.

Thr first step is to get the VS from our github:

git clone h vue-storefront

Then you need to download all the npm packages and start the installer:

cd vue-storefront 
yarn install
npm run installer

The interactive installer is pretty easy to use — please take a look at screen from my session above. To better get what we just did:

It usually takes a while and after successful install, you should see the following screen:

It means that:

Don’t hesitate to enter https://localhost:3000 in your beloved browser to see the default VS theme :)

If anything went wrong you can open the logs:

cat var/log/install.log

Then you can try to install the whole project step by step locally to find out what exactly went wrong — here is a doc for that.

Troubleshooting — use this only in case of problems :)

The checklist for you to check if everything is just fine in case of Troubleshooting:

How to restart everything?

OK, so if installer succeeded you have all projects up and running and can focus on development part. But after you restart the whole environment here is a shortlist of steps to have it again up and running :)

How to integrate Magento 2 with your local instance?

Ok, so we went thru the basics and we’re ready for the final punch! Magento 2 installation.

First of all you need to install mage2vuestorefront — which is pretty simple (docs):

git clone
cd mage2vs/src
npm install

The tool is using Magento 2 API via Oauth authorization, so you need to prepare Magento Integration access at first. Go to your Magento 2 admin panel and click: System -> Integrations

Then click Add new integration and just fill:

  • Name (whatever)
  • your password to confirm the changes,
  • check Catalog, Sales, My Account and Carts on API permissions tab — save

In the result you’ll click Activate and get some oauth access tokens:

It’s cool! Almost done. Please edit the src/config.js file in your mage2vuestorefront directory to set the following section:

magento: {
url: process.env.MAGENTO_URL || ‘',
consumerKey: process.env.MAGENTO_CONSUMER_KEY || ‘alva6h6hku9qxrpfe02c2jalopx7od1q’,
consumerSecret: process.env.MAGENTO_CONSUMER_SECRET || ‘9tgfpgoojlx9tfy21b8kw7ssfu2aynpm’,
accessToken: process.env.MAGENTO_ACCESS_TOKEN || ‘rw5w0si9imbu45h3m9hkyrfr4gjina8q’,
accessTokenSecret: process.env.MAGENTO_ACCESS_TOKEN_SECRET || ‘00y9dl4vpxgcef3gn5mntbxtylowjcc9’,

As you may see - you can override the defaults by ENV variables as well.

OK! The rest of config.js files points out to your vue-storefront-api based Docker and Redis instances which are required by mage2nosql to work.

To import all the Products, Categories and other important stuff to your Elastic Search instance you should run the following commands (the sequence of commands is important — as for example node cli.js categories populates Redis cache for the further use of node cli.js products and so on)

node cli.js taxrule
node cli.js attributes
node cli.js categories
node cli.js productcategories
node cli.js products

It’s safe to run these commands over and over as they’re doing upsert operation — so inserts or updates the existing records.

cli.js as you may check do have lot of other modes to be run in. Dynamic changes, queue support etc. You may experiment with them, but remember — the basic sequence for syncing the whole Magento 2 database is like just shown.

How to synchronize orders, shopping carts and Magento images?

As you should have the products and categories already synchronized you may want to send some orders back to Magento or synchronize the shopping carts in the real time :)

vue-storefront-api is responsible for this write access to Magento. You may want just edit your conf/local.json within vue-storefront-api directory to set the oauth Magento API access (magento2 section)

To allow vue-storefront-api to resize your Magento’s images, please edit the “imgUrl” property under “magento2” section and add your Magento’s domain to “imageable” -> “whitelist”.

Remember: After channing the config files you need to restart npm run dev

After setting up the Magento access you just need to run the Order2Magento worker which works on Redis based queue to process all the orders made by users:

npm run o2m

The code of this script is located here — so you can easily check how it’s working.

Shopping carts

The last thing to synchronize are the shopping carts. By default shopping carts are not synchronized in the real time — just after the order is places, Magento 2 cart is created etc.

This was limiting behavior because to get Magento 2 shopping cart promotion rules into the action you need to keep the user cart most current all the time.

We have option for that! If you have Magento 2 API configured within the vue-storefront-api you just need to go to vue-storefront/conf/local.json and add

synchronize: true

to “cart” section. Please check the default config for reference.

Thanks! :) The next part will be about code customizations and themes.

If you need any help you may want to access our Slack channel; to get the invitation just send us an e-mail to: