Add Vue Storefront PWA cookbook

docs/cookbook/index.rst

@@ -39,6 +39,7 @@ Shop
     shop/embedding-products
     shop/facebook-login
     shop/cms
+    shop/vue-storefront
 
 .. include:: /cookbook/shop/map.rst.inc
 
@@ -183,3 +184,4 @@ API
     api/how_force_login_already_registered_user_during_checkout
 
 .. include:: /cookbook/api/map.rst.inc
+

docs/cookbook/shop/map.rst.inc

@@ -6,3 +6,4 @@
 * :doc:`/cookbook/shop/embedding-products`
 * :doc:`/cookbook/shop/disabling-localised-urls`
 * :doc:`/cookbook/shop/cms`
+* :doc:`/cookbook/shop/vue-storefront`

docs/cookbook/shop/vue-storefront.rst

@@ -0,0 +1,194 @@
+How to use Vue Storefront PWA with Sylius?
+==========================================
+
+.. note::
+    `What are PWAs (Progressive Web Apps)? <https://en.wikipedia.org/wiki/Progressive_web_app>`_
+
+2. What is Vue Storefront?
+--------------------------
+
+Vue Storefront is an open-source, platform-agnostic, Progressive Web App (PWA) framework 
+for building e-commerce applications. It is built using Vue.js for building user interfaces. 
+You can think about it as a USB standard for eCommerce frontends - with Vue Storefront 
+you get what is required by a PWA standard in a nice, platform-agnostic environment meaning 
+it could be connected to any eCommerce backend, including Sylius.
+
+3. How to use Vue Storefront with Sylius?
+-----------------------------------------
+
+In order to use Vue Storefront with Sylius you can use the official integration approved 
+by both Sylius and Vue Storefront. The integration was built by `BitBag <https://www.bitbag.io>`_, 
+Sylius' leading partner. 
+The backend part of the integration can be accessed in the GitHub repository 
+at `BitBag's organization <https://github.com/BitBagCommerce/SyliusVueStorefront2Plugin>`_.
+This part adds all the necessary GraphQL endpoints to Sylius, making it compatible with the Vue Storefront standards. 
+The frontend part could be found under the same organization's package named
+`SyliusVueStorefront2Frontend package <https://github.com/BitBagCommerce/SyliusVueStorefront2Frontend>`_. 
+If you want to see it in action check out the `VSF Demo <https://vsf2-demo.bitbag.io>`_.
+
+4. Installation - the backend part
+----------------------------------
+
+This part refers to installing the API backend, based on the `SyliusVueStorefront2Plugin <https://github.com/BitBagCommerce/SyliusVueStorefront2Plugin>`_. 
+Original content could be accessed at `this <https://github.com/BitBagCommerce/SyliusVueStorefront2Plugin/blob/main/doc/installation.md>`_  
+repository page.
+
+* Require plugin with composer:
+
+.. code-block:: bash
+
+    composer require ``bitbag/vue-storefront2-plugin``
+
+* Add plugin dependencies to your ``config/bundles.php`` file:
+
+.. code-block:: php
+
+    return [
+     ...
+
+        BitBag\SyliusVueStorefront2Plugin\BitBagSyliusVueStorefront2Plugin::class => ['all' => true],
+    ];
+
+* Enable API in ``config/services.yaml``:
+
+.. code-block:: yaml
+
+    sylius_api:
+        enabled: true
+
+* Add plugin mapping path to your ``config/packages/api_platform.yaml`` file as the last element:
+
+.. code-block:: yaml
+
+    api_platform:
+        mapping:
+            paths:
+                - '%kernel.project_dir%/vendor/bitbag/vue-storefront2-plugin/src/Resources/api_resources'
+
+* Import serialization files in ``config/packages/framework.yaml`` file:
+
+.. code-block:: yaml
+
+    framework:
+        serializer:
+            mapping:
+                paths:
+                    - '%kernel.project_dir%/vendor/bitbag/vue-storefront2-plugin/src/Resources/serialization'
+
+* Import plugin config files in ``config/packages/bitbag_sylius_vue_storefront2_plugin.yaml``:
+
+.. code-block:: yaml
+
+    imports:
+        - { resource: "@BitBagSyliusVueStorefront2Plugin/Resources/config/services.xml" }
+
+You are free to adjust two parameters in the same file:
+
+.. code-block:: yaml
+
+    bitbag_sylius_vue_storefront2:
+        refresh_token_lifespan: 2592000 # default value
+        test_endpoint: 'http://127.0.0.1:8080/api/v2/graphql' # default value
+
+* Add some external Doctrine mappings:
+
+.. code-block:: yaml
+
+    doctrine:
+        orm:
+            mappings:
+                VueStorefront2:
+                    is_bundle: false
+                    type: xml
+                    dir: '%kernel.project_dir%/vendor/bitbag/vue-storefront2-plugin/src/Resources/doctrine/model'
+                    prefix: 'BitBag\SyliusVueStorefront2Plugin\Model'
+                    alias: BitBag\SyliusVueStorefront2Plugin
+
+* Change the Sylius Taxon repository class to add some queries required by GraphQL in ``config/packages/_sylius.yaml``:
+
+.. code-block:: yaml
+
+    sylius_taxonomy:
+       resources:
+          taxon:
+             classes:
+                repository: BitBag\SyliusVueStorefront2Plugin\Doctrine\Repository\TaxonRepository
+
+* If you're extending Sylius `ProductAttributeValue` entity:
+
+Please use our trait inside: ``BitBag\SyliusVueStorefront2Plugin\Model\ProductAttributeValueTrait``. 
+Otherwise, please create an entity, which uses the trait and setup the Sylius resource in ``config/packages/_sylius.yaml``. 
+
+Read more on how to customize models in a `different part of Sylius docs <https://sylius-older.readthedocs.io/en/latest/customization/model.html>`_ 
+if you are not familiar with the process yet.
+
+.. code-block:: yaml
+
+    sylius_attribute:
+        driver: doctrine/orm
+        resources:
+            product:
+                subject: Sylius\Component\Core\Model\Product
+                attribute_value:
+                    classes:
+                        model: App\Entity\ProductAttributeValue
+
+* Add a new column to the ProductAttributeValue entity in your Doctrine configuration file: 
+
+We are using XML for Doctrine mappings but you are free to rewrite it to Annotations or YAML.
+
+.. code-block:: xml
+
+    <?xml version="1.0" encoding="UTF-8"?>
+
+    <doctrine-mapping
+        xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
+        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+        xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
+                                http://doctrine-project.org/schemas/orm/doctrine-mapping.xsd"
+    >
+        <entity name="App\Entity\ProductAttributeValue" table="sylius_product_attribute_value">
+            <indexes>
+                <index name="locale_code" columns="locale_code" />
+            </indexes>
+        </entity>
+    </doctrine-mapping>
+
+* Import routing in ``config/routes.yaml``:
+
+.. code-block:: yaml
+
+    bitbag_sylius_vue_storefront2_plugin:
+        resource: "@BitBagSyliusVueStorefront2Plugin/Resources/config/routing.yml"
+
+The process seems a bit complex but is required to set up everything properly. 
+If something went wrong in your instance at this stage make sure you followed this doc properly step by step.
+and check this sample configuration in the plugin environment `plugin environment <https://github.com/BitBagCommerce/SyliusVueStorefront2Plugin/tree/main/tests/Application>`_.
+
+4. Installation - the frontend part
+-----------------------------------
+
+* Clone the frontend repository:
+
+.. code-block:: bash
+
+    git clone git@github.com:BitBagCommerce/SyliusVueStorefront2Frontend.git && cd SyliusVueStorefront2Frontend
+
+* Copy the ``packages/theme/.env.dist`` file to ``packages/theme/.env`` and configure your environment in the file:
+
+* Install dependencies:
+
+.. code-block:: bash
+
+    yarn install
+
+* Run the application in dev mode:
+
+.. code-block:: bash
+
+    yarn dev
+
+For production mode use ``yarn start`` command instead.
+
+That is it. You are now able to start your journey with Vue Storefront in your Sylius instance. 
+For more details follow `official Vue Storefront documentation <https://docs.vuestorefront.io/v2/>`_.