React Hyva Checkout is an <a href="https://chop-chop.org/blog/e-commerce-react-hyva-checkout-for-magento" target="_blank" rel="noreferrer noopener">open-source extension for Magento 2</a>, designed to enhance the checkout process for online stores. It is built on ReactJS, a JavaScript library for building user interfaces, and offers a streamlined, modern, and responsive checkout experience for customers. In this guide, we'll cover how to install and customize the React Hyva Checkout from a developer's perspective.

Before we get started, make sure you have the following prerequisites in place:

A running Magento 2 store (from  2.3.9 up, however, preferred 2.4.5)

A basic understanding of <a href="https://react.dev/" target="_blank" rel="noreferrer noopener">ReactJS</a> and JavaScript

<a href="https://nodejs.org/en" target="_blank" rel="noreferrer noopener">Node.js</a> installed on your system

Installing React Hyva Checkout

Follow these steps to install React Hyva Checkout on your Magento 2 store:

In order to install React Hyva Checkout, the best approach is to use composer with the following command composer require hyva-themes/magento2-react-checkout

Next in order to activate React Hyva Checkout as the default checkout use the command bin/magento config:set hyva_react_checkout/general/enable 1

This is the recommended approach, however you can also clone the repository into your project and customize it directly (we have another way for this using a custom module just for customization, which will be shown later). To do so move to the root of your Magento 2 project

Clone the React Hyva Checkout repository from GitHub  using the following command:

git clone https://github.com/hyva-themes/magento2-hyva-checkout.git app/code/Hyva/Checkout

Next, run the following commands in the root directory of your Magento 2 installation:

bin/magento module:enable Hyva_Checkout bin/magento setup:upgrade bin/magento setup:static-content:deploy -f bin/magento cache:clean

Finally, refresh your browser and you should see the React Hyva Checkout enabled on your Magento 2 store.

Adding Payment and Shipping Gateways in React Hyva Checkout

React Hyva Checkout supports a wide range of payment and shipping gateways, which can be easily integrated into your Magento 2 store.

Adding a Payment Gateway

To add a payment gateway to React Hyva Checkout, follow these steps:

Depending upon the payment methods, you may have some special configuration settings in your store. Usually, you do this under Stores > Configuration.

If you are familiar with the default Magento 2 checkout page, then you may know that Magento 2 passes this configuration via a global variable which you can find at window.checkoutConfig.

To collect these checkout configurations, we have a ViewModel (Hyva\ReactCheckout\ViewModel\CheckoutConfigProvider) available in the module, and we are passing this configuration through the root DOM element.

See the layout file where we inject the view model, the file is both present in the original module and in the module we suggest using for customizations.

File: src/view/frontend/layout/hyva_reactcheckout_index.xml

&lt;?xml version="1.0"?>
&lt;page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" layout="1column" xsi:noNamespaceSchemaLocation="urn
framework:View/Layout/etc/page_configuration.xsd">
    ...
    &lt;body>
        &lt;referenceContainer name="content">
            &lt;block
                cacheable="false"
                name="checkout.container"
                template="Hyva_ReactCheckout::react-container.phtml"
            >
                &lt;arguments>
                    &lt;argument
                        name="checkout_config_provider"
                        xsi:type="object">Hyva\ReactCheckout\ViewModel\CheckoutConfigProvider&lt;/argument>
                &lt;/arguments>
            &lt;/block>
        &lt;/referenceContainer>
        ...
    &lt;/body>
&lt;/page>

See the data attribute data-checkout_configuration through which we are passing this configuration.

File: src/view/frontend/templates/react-container.phtml

&lt;?php
...
/** @var \Magento\Framework\Escaper $escaper */
/** @var \Hyva\ReactCheckout\ViewModel\CheckoutConfigProvider $configProvider */
$configProvider = $block->getCheckoutConfigProvider();
...
?>
&lt;div
    id="react-checkout"
    ...
    data-checkout_config="&lt;?= $escaper->escapeHtmlAttr($configProvider->getConfig())  ?>"
>
...
&lt;/div>

Now the React app has access to the payment configurations, and it can be used in the application according to your need.

Adding a Shipping Gateway

To add a shipping gateway to React Hyva Checkout, follow these steps:

Install the shipping gateway extension for Magento 2 using the instructions provided by the extension developer.

Open the src/components/ShippingMethods.js file and add a new shipping method component for the shipping gateway. For example, if you are using the DHL shipping gateway, you can add the following code:

import DhlShippingMethod from './DhlShippingMethod';

...

const shippingMethods = [
  ...

  {
    component: DhlShippingMethod,
    code: 'dhl',
  },
];

Create a new file DhlShippingMethod.js in the src/components directory and add the code to render the shipping gateway form. For example, if you use the DHL shipping gateway, you can add the following code:

import DhlShippingMethod from './DhlShippingMethod';

...

const shippingMethods = [
  ...

  {
    component: DhlShippingMethod,
    code: 'dhl',
  },
];
export default DhlShippingMethod;

Finally, compile the JavaScript bundle using the npm run build command, and refresh your browser to see the new shipping gateway option on the checkout page.

How to solve possible issues

While customising React Hyva Checkout, you may encounter some issues. Here are some common issues and their solutions:

Issue: Changes are not reflected in the checkout page

Solution: Make sure to format the code using Prettier before compiling the JavaScript bundle. You can use the prettier --write . command to format the code. Also, ensure that you have compiled the JavaScript bundle using the npm run build command and have refreshed the checkout page.

Issue: Payment or shipping gateway not working

Solution: Make sure that you have installed the payment or shipping gateway extension for Magento 2 and have followed the instructions provided by the extension developer to configure it correctly. Also, ensure that you have added the corresponding payment or shipping method component in the PaymentMethods.js or ShippingMethods.js file, respectively, and have provided the correct code for it.

Issue: JavaScript errors on the checkout page

Solution: Check the browser console for any JavaScript errors and fix them. Also, ensure that you have installed the dependencies using the npm install command and have compiled the JavaScript bundle using the npm run build command.

Hyvä CheckoutExample Module Template

It is an example project that demonstrates how to use the hyva-react-checkout module to create a custom checkout page for Magento 2.

hyva-themes/magento2-checkout-example provides a starting point for customizing the React Hyva Checkout page, with pre-built payment and shipping gateway components. It also includes a docker-compose.yml file that can be used to set up a development environment.

Here is how to customize the module using this starting point:

Clone the hyva-themes/magento2-checkout-example repository using git clone https://github.com/hyva-themes/magento2-checkout-example.git.

Navigate into the project directory and run docker-compose up -d to start the development environment.

Install the Magento 2 instance by running docker-compose exec php bin/magento setup:install.

Install the hyva-react-checkout module using docker-compose exec php bin/magento module:enable Hyva_Checkout.

Run docker-compose exec php bin/magento setup:upgrade to apply the changes.

Open your browser and navigate to http://localhost:8000 to see the custom checkout page.

To customize the checkout components, navigate to the src directory in the project directory. This directory contains the source code for the checkout components.

To modify an existing component, navigate to its directory in the src/components directory and make the desired changes. For example, to modify the billing address component, navigate to src/components/billing-address and modify the files as needed.

To add a new component, create a new directory in the src/components directory and add the necessary files. You can use the existing components as a guide for creating new ones.

After making changes to the components, run npm run build to compile the JavaScript bundle.

Clear the Magento 2 cache by running docker-compose exec php bin/magento cache:clean.

Refresh the checkout page in your browser to see the changes.

React Hyva Checkout is an open-source extension for Magento 2 that improves the checkout process with a modern and responsive user interface using ReactJS. It can be installed using Composer or by cloning the repository. Payment and shipping gateways can be added by configuring them in the Magento 2 admin panel and injecting the necessary configurations through the DOM. Troubleshooting may involve code formatting, gateway extension installation, and debugging JavaScript errors. The Hyvä CheckoutExample Module Template provides a starting point for customizing the React Hyva Checkout page and includes a development environment setup.

Do you need help with the development of your e-commerce to drive much better results and sales? <a href="https://chop-chop.org/contact" target="_blank" rel="noreferrer noopener">Don't hesitate to contact us</a>! We're ready to help!