Vue Storefront — how to install and integrate with Magento2
Here is a short tutorial for developers — on how to connect Vue Storefront to Magento2 instance and develop your own customizations. It’s probably a good starting point for you first VS based implementation. So, let’s get started!
Intro
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 (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 consist of docker instances for Redis and ElasticSearch required by mage2vuestorefront and pimcore2vuestorefront
mage2vuestorefront (Github)or pimcore2vuestorefront (Github) — data bridges which are in charge of moving data back from Magento2 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 very important assumption you must keep in mind while developing your custom code.
Disclaimer
Vue Storefront is well tested on MacOS and Linux platform. 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.
Requirements
To complete this tutorial, You need to have:
- latest version of Docker installed,
- node.js, version > 8.0.0 installed,
- imagemagick command if you’re installing vue-storefront-api locally — to have Image Proxy in command
Installation
To get started — first of all we need to install all projects on your local machine. Fortunately it’s very simple step because we do have CLI installer which installs vue-storefront and vue-storefront-api altogether.
First step is to get the VS from our github:
git clone https://github.com/DivanteLtd/vue-storefront.git 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:
- first question is about backend — if you’re Windows user — you may use backend from our servers (demo.vuestorefront.io) — in this case you will not be able to integrate with Magento and you must use our standard demo database — but you can focus on development the frontend part, no problem. We answered No because we would like to have vue-storefront-api installed!
- Then you provide the git path — in 99,9% cases is just a “git” if you have git installed in your PATH,
- Then you must choose the image-proxy path; Image proxy is part of vue-storefront-api and it’s responsible for resizing the images served from Magento; if you don’t plan to install vue-storefront-api locally just use demo.vuestorefront.io/img as a endpoint here; otherwise please choose http://localhost:8080/img as we did :)
- That’s all! :)
It usually takes a while and after successful install you should see the following screen:
It means that:
- you’ve got docker instances for Elastic Search and Redis up and running
- you’ve got vue-storefront-api up and running on localhost:8080
- you’ve got vue-storefront up and running on localhost:3000
Don’t hesitate to enter http://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:
- you must have docker and redis instances up and running (docker-compose up in vue-storefront-api directory)
- you must run yarn install and then npm run dev in both vue-storefront and vue-storefront-api; moreover — you must copy the default conf/default.json -> conf/local.json and adjust your settings.
- you must have default data imported (npm run migrate within vue-storefront-api directory),
- you must have npm run migrate executed within vue-storefront-api directory to have the database structure migrated to the latest version.
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 short list of steps to have it again up and running :)
- goto vue-storefront directory and run npm run dev
- goto vue-storefront-api directory and run: docker-compose up -d and then npm run dev
- That’s all :)
How to integrate Magento2 with your local instance?
Ok, so we went thru the basics and we’re ready for the final punch! Magento2 installation.
First of all you need to install mage2vuestorefront — which is pretty simple (docs):
git clone https://github.com/DivanteLtd/mage2vuestorefront.git mage2vs
cd mage2vs/src
npm install
The tool is using Magento2 API via Oauth authorization, so you need to prepare Magento Integration access at first. Go to your Magento2 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 || ‘http://magento2.demo-1.divante.pl/rest/',
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 Magento2 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, Magento2 cart is created etc.
This was limiting behavior because to get Magento2 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 Magento2 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. As for now you may just take a look at our dev docs:
If you need any help you may want to access our Slack channel; to get the invitation just send us an e-mail to: contributors@vuestorefront.io
