Hyvä React Checkout for Magento 2

repository·main·Indexed 41 days ago

https://github.com/friends-of-hyva/magento2-react-checkout

A highly customizable React-based checkout foundation for Magento 2, designed to replace the default checkout experience. Version 1.0.3 provides a toolbox for developers to build bespoke checkout flows, featuring integration scripts for custom payment and shipping methods, and a comprehensive API for cart management, including functions like placeOrder(), mergeCarts(), and applyCouponCodeToCart.

Tokens
19.5K
Snippets
95
Records
103
Agent score
52%

What's inside Hyvä React Checkout

  1. How the React Checkout works and requirements

    main

    The React Checkout is loaded at [store-url]/hyvareactcheckout/reactcheckout. When enabled via hyva_react_checkout/general/enable, it replaces the default Magento checkout.

    Data Requirements

    The checkout relies on two specific keys being present in localstorage:

    1. signin_token (within the customer section)
    2. cartId (within the cart section)

    Dependencies

    For Hyvä Themes or default Magento frontends, you must use hyva-themes/magento2-graphql-tokens to ensure these tokens are correctly added to the customerSections.

  2. Install Hyvä React Checkout via Composer

    main

    To install the checkout as a demo or for testing purposes, use Composer to add the package to your Magento 2 installation.

    Via Packagist:

    composer require hyva-themes/magento2-react-checkout

    Via GitHub:

    composer config repositories.hyva-themes/magento2-react-checkout git git@github.com:friends-of-hyva/magento2-react-checkout.git
    composer require hyva-themes/magento2-react-checkout

    After installation, run the Magento setup upgrade command to enable the module.

    composer require hyva-themes/magento2-react-checkout
    bin/magento setup:upgrade
  3. Customizing the React Checkout

    main

    This module is intended to be used as a toolbox rather than a plug-and-play solution. To build a custom checkout tailored to your specific needs, it is recommended to use an extension mechanism rather than modifying the core module directly.

    Recommended approach: Use the magento2-react-checkout-example repository. This provides an extension mechanism that allows you to build your own checkout based on this core repository.

  4. Use customRenderers.js to port shipping renderers

    main

    The file ./src/shippingMethods/customRenderers.js acts as a central registry for all shipping method renderers. It aggregates imports from various shipping method directories (cloned from your configured repositories) and exports them as a single object.

    If you are adding local shipping methods that are not managed via the shippingMethodsRepo config, you must manually add them to this file following the existing pattern.

    /**
     * 📢 📢 📢 This file is autogenerated and may be overwritten. Handle with care. 🙅🏽 🙅🏽 🙅🏽
     */
    
    import myCustomMethodRenderers from './myCustomMethod/renderers';
    
    export default {
      ...myCustomMethodRenderers,
    };
  5. Enable the React Checkout in Magento

    main

    Once the module is installed, you must enable it via the Magento Admin Panel or the configuration path to replace the default checkout with the React version.

    Admin Path: HYVA THEMES -> React Checkout -> General Settings -> Enable

    Configuration Path: hyva_react_checkout/general/enable

  6. Configure custom payment methods via package.json

    main

    To integrate custom payment methods into the React checkout app, you must specify the repository URLs in your package.json file using the paymentMethodsRepo configuration key.

    When you run npm install, the integration script will:

    1. Clone the specified repositories into ./src/paymentMethods/.
    2. Automatically generate (or overwrite) ./src/paymentMethods/customRenderers.js to export the renderers from those repositories.

    Note: The generated customRenderers.js file is autogenerated and will be overwritten during npm install. If you have local custom payment methods that are not in a remote repository, you must manually add them to this file.

    {
      "paymentMethodsRepo": {
        "methodName1": "https://github.com/user/repo-method1.git",
        "methodName2": "https://github.com/user/repo-method2.git"
      }
    }
  7. Configure custom shipping methods via package.json

    main

    To integrate custom shipping methods into the React application, you must specify the repository URL in your package.json file using the shippingMethodsRepo configuration key.

    When you run npm install, the integration script will:

    1. Clone the specified repository into ./src/shippingMethods/.
    2. Automatically generate (or update) ./src/shippingMethods/customRenderers.js to include the renderers from your custom repository.

    Note: The generated customRenderers.js file is autogenerated and may be overwritten during npm install. If you have local custom shipping methods that are not part of a remote repository, you must manually add them to this file.

    {
      "shippingMethodsRepo": {
        "my-custom-shipping-methods": "https://github.com/user/repo.git"
      }
    }
  8. Manually add local payment methods to customRenderers.js

    main

    If you are developing custom payment methods locally and they are not being pulled via a git repository in package.json, you must manually update ./src/paymentMethods/customRenderers.js to ensure they are available in the React app.

    The file uses a spread pattern to export renderers. For each method, you must add an import statement and include its renderers in the default export object.

    /**
     * 📢 📢 📢 This file is autogenerated and may be overwritten. Handle with care. 🙅🏽 🙅🏽 🙅🏽
     */
    
    import methodOneRenderers from './methodOne/renderers';
    import methodTwoRenderers from './methodTwo/renderers';
    
    export default {
      ...methodOneRenderers,
      ...methodTwoRenderers,
    };
  9. Extend checkout configuration via the hyva_react_checkout_config event

    main

    The CheckoutConfigProvider class provides the configuration required by the React checkout application. It currently focuses on payment configuration and essential store metadata.

    Developers can intercept and modify the configuration data before it is serialized and sent to the frontend by listening to the hyva_react_checkout_config event. This is the primary extension point for adding custom configuration keys to the React app.

    When the event is dispatched, it carries a transport object (an instance of ext{Magento extbackslash Framework extbackslash DataObject}) containing:

    • checkoutConfig: The full Magento checkout configuration.
    • output: The specific subset of data that will be serialized and sent to the frontend. This includes:
      • storeCode: The current store code.
      • payment: The payment configuration (including a calculated restUrlPrefix in the format /rest/{storeCode}/V1/).
      • language: The current locale string.
      • currency: The currency configuration provided by CurrencyProvider.
      • defaultCountryId: The default country ID from the checkout configuration.
    <?php
    // Example observer implementation
    
    public function execute(\Magento\Framework\Event\Observer `$observer`)
    {
        $transport = $observer->get('transport');
        $output = $transport->getData('output');
    
        // Add custom data to the output array
        $output['my_custom_key'] = 'my_value';
    
        // Update the transport with the modified output
        $transport->setData('output', $output);
    }
  10. Fetch the logged-in customer's cart with getCustomerCart

    main

    Use the getCustomerCart function to retrieve the current cart data for the logged-in customer. This is the primary entry point for accessing the customer's active cart within the React application.

    import getCustomerCart from './api/customer/fetchCustomerCart';
    
    // Example usage (usage pattern based on function name/purpose):
    const cart = await getCustomerCart();