How to Set up Hyvä React Checkout in Magento 2?

This blog post is your ultimate guide to Hyvä React Checkout. 

If you want to make your Magento 2 store checkout faster yet developer-friendly, this guide will be helpful to you.  

Let’s dive right in.

What is Hyvä React Checkout?

Hyvä React Checkout is an open-source Magento 2 module that improves the performance of the checkout page using ReactJS.

Making the customization much simpler for developers. 

The default Luma theme completely works on uiComponents. A combination of Knockout.js, jQuery, and RequireJS, aka old JavaScript libraries, makes it harder for developers to comprehend. 

Secondly, this Hyvä React-based Checkout works well with speed. 

A default Luma checkout requires more than 400 javascript and template files to load, while the Hyvä React Checkout takes only one JavaScript file (less than 100kb in size) to render the entire checkout page. 

Using the Hyvä React Checkout:

• Your checkout page loads faster using a single JavaScript file
• You work with less complicated JavaScript files
• Get better customization options for developers 

Hyvä React Checkout vs Hyvä Checkout – What’s the Difference?

Hyvä React Checkout and Hyvä Checkout are two checkout solutions for Magento 2, but they are different. 

Elements	Hyvä React Checkout	Hyvä Checkout
Cost	Free	Paid plans: – Yearly subscription: €1000 (license cost) + €250   – One-time cost: €2000 (license cost included)
Best for	Customizing checkout	Improving checkout performance
Compatibility	Hyvä theme, Luma, or headless	Hyvä theme only
Tech stack	Built with React	AlpineJS and Tailwind CSS

Hyvä Checkout is ideal for stores built on the Hyvä theme and works more like an add-on feature to improve the checkout experience. 

On the other hand, Hyvä React Checkout gives flexibility to Luma theme store owners and others to add more customization to their existing stores. 

How to Install & Use Hyvä React Checkout? (for Developers)

Step 1: Install via Composer

Objective: Install the Hyvä React Checkout module and its dependencies in your Magento 2 environment.

• Add the Hyvä React Checkout Repository:

Use Composer to configure the repository and install the module:
composer config repositories.hyva-themes/magento2-react-checkout git [email protected]:hyva-themes/magento2-react-checkout.git

• composer require hyva-themes/magento2-react-checkout
• Ensure you have access to the repository (public or via SSH key for private access).

• Install GraphQL Tokens Module (if needed):
  • For customer session handling, install the hyva-themes/magento2-graphql-tokens module if using Hyvä Themes or Magento’s default frontend:
    composer require hyva-themes/magento2-graphql-tokens
• Run Magento Setup Commands:
  • Update the Magento database schema and enable the module:
    bin/magento setup:upgrade
  • Deploy static content (for production mode):
    bin/magento setup:static-content:deploy
  • Clear the cache:
    bin/magento cache:flush
• Verify Installation:
  • Check that the module appears in app/etc/config.php under Hyva_ReactCheckout => 1.
  • In developer mode, navigate to [store-url]/hyva/reactcheckout to confirm the checkout loads.

Step 2: Configure Checkout

Objective: Set up the Hyvä React Checkout module and customize its environment for your store.

• Enable the Module:
  • In the Magento Admin Panel, go to Stores > Configuration > Hyvä React Checkout > General.
  • Set Enable to Yes to activate the React Checkout, overriding the default Magento checkout.
• Configure Environment Variables:
  • Navigate to the React app directory: vendor/hyva-themes/magento2-react-checkout/src/reactapp.
  • Copy env.example to .env and configure key variables:
    • REACT_APP_BASE_URL: Your Magento backend URL (e.g., http://yourstore.com).
    • REACT_APP_STORE_CODE: Store code for GraphQL queries (e.g., default).
    • REACT_APP_LANGUAGE: Locale (e.g., en_US).
    • REACT_APP_CURRENCY_CODE: Currency (e.g., USD).
    • REACT_APP_CURRENCY_SYMBOL: Currency symbol (e.g., $).
    • REACT_APP_DEFAULT_COUNTRY: Default country for address fields (e.g., US).
• Set Up Payment Methods:
  • Identify the payment methods your store uses (e.g., PayPal, Stripe, or custom).

Add payment method repositories to reactapp/package.json under config.paymentMethodsRepo. Example:

"config": {
  "paymentMethodsRepo": {
    "myPayment": "[email protected]:your-repo/magento2-hyva-checkout-my-payment.git"
  }

• }
• Run npm install in the reactapp directory to fetch these repositories.
• Test Configuration:

Run the React app locally for testing:
cd vendor/hyva-themes/magento2-react-checkout/src/reactapp

npm install

• npm start
• Access http://localhost:3000, enter a valid Magento cart ID, and verify that the checkout renders with your store’s data.

Step 3: Deploy the React Checkout

Objective: Build and deploy the React app, integrate customizations, and ensure the checkout is production-ready.

• Customize the Checkout:
  • Use the Checkout Example Template for maintainable customizations:
    composer require hyva-themes/magento2-checkout-example
    • Set up the module in app/code/Hyva/CheckoutExample.
    • Copy only the React components you need to modify from vendor/hyva-themes/magento2-react-checkout/src/reactapp/src to your module’s reactapp/src.
    • Update Webpack aliases in your module’s reactapp/webpack.config.js to resolve imports (e.g., @hyva/react-checkout).
  • Alternatively, fork the repository or copy to app/code, but note that these approaches complicate updates.
• Build the React App:
  • In the reactapp directory, build the production-ready JavaScript bundle:
    npm run build
  • This generates react-checkout.es.min.js and other assets in src/view/frontend/web/.
• Deploy Static Content:
  • In production mode, deploy the static files:
    bin/magento setup:static-content:deploy
  • Clear the cache if necessary:
    bin/magento cache:flush
• Integrate Custom Payment Renderers:

For each payment method, create a renderer in src/reactapp/src/paymentMethods/<method>/renderers.js. Example:

import React, { useEffect } from 'react';
import { func, shape, string } from 'prop-types';
import RadioInput from '@hyva/react-checkout/components/common/Form/RadioInput';
import usePaymentMethodCartContext from '@hyva/react-checkout/components/paymentMethod/hooks/usePaymentMethodCartContext';

function MyPayment({ method, selected, actions }) {
  const methodCode = method.code;
  const isSelected = methodCode === selected.code;
  const { setPaymentMethod } = usePaymentMethodCartContext();

  useEffect(() => {
    if (isSelected) {
      (async () => {
        await setPaymentMethod(methodCode);
      })();
    }
  }, [setPaymentMethod, methodCode]);

  return (
    <div>
      <RadioInput
        label={method.title}
        name="paymentMethod"
        value={method.code}
        onChange={actions.change}
        checked={isSelected}
      />
      {isSelected && <div>{/* Custom form or iframe */}</div>}
    </div>
  );
}

MyPayment.propTypes = {
  method: shape({ code: string.isRequired, title: string.isRequired }).isRequired,
  selected: shape({ code: string.isRequired }),
  actions: shape({ change: func.isRequired }).isRequired,
};

• export default { myPayment: MyPayment };
• Test renderers locally using npm start.
• Test Deployment:
  • Navigate to [store-url]/hyva/reactcheckout and test the full checkout flow (cart, address entry, payment, order placement).
  • Verify Tailwind CSS styles and resolve any conflicts with non-Hyvä themes by including Hyva_ReactCheckout::css/styles.css in your layout.

Optional Step: Disable the Default Hyvä Checkout

Objective: Ensure only the React Checkout is active if using Hyvä Themes with the commercial Hyvä Checkout.

• Check for Hyvä Checkout:
  • If your store uses Hyvä Themes, the commercial hyva-themes/magento2-hyva-checkout module may be installed.
  • Verify its presence in composer.json or vendor/hyva-themes/magento2-hyva-checkout.
• Disable the Commercial Checkout:
  • In the Magento Admin Panel, go to Stores > Configuration > Hyvä Checkout > General.
  • Set Enable to No to disable the Magewire-based Hyvä Checkout.

Alternatively, disable the module via CLI:
bin/magento module:disable Hyva_Checkout

bin/magento setup:upgrade

• bin/magento cache:flush
• Resolve Conflicts:
  • If both hyva-themes/magento2-hyva-checkout and hyva-themes/magento2-react-checkout are installed, autoload errors may occur.

Remove the commercial checkout module from composer.json and vendor/:
composer remove hyva-themes/magento2-hyva-checkout

composer install

bin/magento setup:upgrade

• bin/magento setup:di:compile
• Verify:
  • Ensure [store-url]/hyva/reactcheckout loads the React Checkout without conflicts.
  • Test the checkout flow to confirm the default or commercial checkout is no longer active.

Solutions to Common Problems Using Hyvä React Checkout

Checkout Page Not Showing

Solution: This is a configuration issue. Check that you have properly installed  Hyvä React Checkout and activated it from your Magento 2 admin. 

CSS Conflicts with Theme

Solution: This happens because Hyvä uses Tailwind CSS, which differs from the Luma theme. Avoid overrides since the official document says some CSS issues might be expected in this process.

JS Errors on Checkout Page

Solution: Check the issues with the JavaScript and fix them using the browser console. Also, install the dependencies using the npm install command and compile the JavaScript bundle using the npm run build command.

Payment / Shipping Method Not Showing

Solution:Make sure you have properly installed the payment/shipping extensions. Then, you correctly added the components to the JS file. 

Frequently Asked Questions 

Is Hyva Theme License Required to Use Hyvä React Checkout?

No, Hyvä React Checkout is a free open-source.  

How to Integrate Custom Payment Method in Hyvä React Checkout?

Make the basic configuration settings and use the ViewModel available in the Hyvä module. 

What are the System Requirements for Hyvä React Checkout?

Magento 2.4.3 or higher, PHP 7.4 or newer, and react environments like: Node.js, React, and Tailwind CSS. 

Can I install Hyvä React Checkout without Composer?

Yes, you can install it without a composer, but it is not recommended. 

Get Started with Custom Hyvä Theme Development

Just like Hyvä React Checkout makes developers’ lives easy, the Hyvä theme is built to make your store faster and more accessible. Hire us to add customization to your Hyvä theme to ensure your store is feature-filled to make an impression and a sale at the same time.