Wednesday, November 4, 2020

SWR: React Hooks For Remote Data Fetching

 

SWR is a lightweight library created by Vercel (formerly ZEIT) that allows fetching, caching, or refetching data in realtime using React Hooks. It’s built with React Suspense which lets your components “wait” for something before they can render, including data. SWR ships also with great features such as dependent fetching, focus on revalidation, scroll position recovery, and so on. It’s also a very powerful tool since it’s backend agnostic and has good support for TypeScript. It’s a package that has a bright future.

Why should you care? You should care if you’ve been looking for a library that does not only fetch data from APIs but also make it possible to do things like caching and dependent fetching. What will be covered in this tutorial will come in handy when building React applications with a lot of moving parts. It’s expected that you should have made use of Axios and the Fetch API, even though we’ll compare how they differ from SWR, we won’t be going into details on how they’ll be implemented.

In this guide, I will introduce you to React Hooks for Remote Data Fetching by building a Pokedex app that requests data from the Pokemon API. We will also dive into other features that come with SWR as well, and highlight its differences compared to popular solutions such as the Fetch API and the Axios library and give you the reasons why using this library and why you should keep an eye on SWR.

So, let’s start by answering a fundamental question: What is SWR?

 

What Is SWR?

SWR is an initialism of stale-while-revalidate. It’s a React Hooks library for remote data fetching. SWR works with three main steps: first, it returns the data from the cache (the stale part), then sends the fetch request (the revalidate part), and finally comes with the up-to-date data. But no worries, SWR handles all these steps for us. The only thing we have to do is give the useSWR hook the needed parameters to make the request.

SWR has also some nice features such as:

  • Back-end agnostic
  • Fast page navigation
  • Revalidation on focus
  • Interval polling
  • Request deduplication
  • Local mutation
  • Pagination
  • TypeScript ready
  • SSR support
  • Suspense mode
  • React Native support
  • Lightweight.

Sounds magical? Well, SWR simplifies things and increases for sure the user experience of your React app. And once we start implementing it in our project, you will see why this hook is handy.

It’s important to know that the name of the package is swr or SWR and the hook used to get SWR features is named useSWR.

In theory, the SWR is maybe what you need to enhance your data fetching. However, we already have two great ways of making HTTP requests in our app: the Fetch API and the Axios library.

So, why using a new library to retrieve data? let’s try answering this legit question in the next section.

Comparison With Fetch And Axios

We already have many ways to make HTTP requests in our React Apps, and two of the most popular is the Fetch API and the Axios library. They are both great and allows us to fetch or send data easily. However, once the operation is done, they will not help us to cache or paginate data, you have to do it on our own.

Axios or Fetch will just handle the request and return the expected response, nothing more.

And compared to SWR, it’s a bit different because the SWR under the hood uses the Fetch API to request data from the server — it’s kind of a layer built on top of it. However, it has some nice features such as caching, pagination, scroll position recovery, dependent fetching, etc, and to be precise a certain level of reactivity out of the box that Axios or Fetch do not have. It’s a big advantage because having such features help to make our React Apps fast and user-friendly and reduce markedly the size of our code.

And to conclude, just keep in mind that SWR is not the same as Axios or Fetch even if it helps to deal with HTTP requests. SWR is more advanced than them, it provides some enhancements to keep our app synchronized with the back-end and hence increases the performance of our app.

Now we know what’s differences SWR has compared to the Axios library or the Fetch API, it’s time to dive into why using such a tool

 

Why Using SWR For Data Fetching?

As I said earlier SWR ships with some handy features that help to increase the usability of your app easily. With SWR, you can paginate your data in no-time using useSWRPages, you can also fetch data that depends on another request or recover a scroll position when you get back to a given page, and so much more.

Usually, we show to the user a loading message or a spinner while fetching data from the server. And with SWR, you can make it better by showing to the user the cached or stale data while retrieving new data from the API. And once that operation is done, it will revalidate the data to show the new version. And you don’t need to do anything, SWR will cache the data the first time you fetch it and retrieve it automatically when a new request is made.

So far, we already see why using SWR over Axios or Fetch is better depending obviously on what you are aiming to build. But for many cases, I will recommend using SWR because it has great features that go beyond just fetching and returning data.

That said, we can now start building our React app and use the SWR library to fetch remote data.

So, let’s start by setting up a new project.

Setting Up

As I said earlier in the introduction, we will build an app that fetches data from the Pokemon API. You can use a different API if you want too, I will stick with it for now.

And to create a new app, we need to run the following command on the terminal:

npx create-react-app react-swr

Next, we need to install the SWR library by first navigating to the folder that holds the React app.

cd react-swr

And run on the terminal the following command to install the SWR package.

yarn add swr

Or if you’re using npm:

npm install swr

Now we have all set up done, let’s structure the project as follow to start using SWR:

src
├── components
|  └── Pokemon.js
├── App.js
├── App.test.js
├── index.js
├── serviceWorker.js
├── setupTests.js
├── package.json
├── README.md
├── yarn-error.log
└── yarn.lock

As you can see, the folder structure is simple. The only thing to notice is the components folder that holds the Pokemon.js file. It will be used later as a presentational component to show a single Pokemon once we get data from the API.

Great! With that in place, we can now start fetching data from the API using useSWR.

Fetching Remote Data

The SWR package has some handy features as we have seen above. However, there are two ways of configuring this library: either locally or globally.

A local setup means that every time we create a new file, we have to setup SWR again to be able to fetch remote data. And a global setup allows us to reuse a part of our configuration within different files because a fetcher function can be declared once and used everywhere.

And no worries, we will see both in this article, but for now, let’s get hands dirty and add some meaningful code in the App.js file.

Displaying The Data

import React from 'react'
import useSWR from 'swr'
import { Pokemon } from './components/Pokemon'

const url = 'https://pokeapi.co/api/v2/pokemon'

const fetcher = (...args) => fetch(...args).then((res) => res.json())

function App() {
    const { data: result, error } = useSWR(url, fetcher)

    if (error) return <h1>Something went wrong!</h1>
    if (!result) return <h1>Loading...</h1>

    return (
        <main className='App'>
            <h1>Pokedex</h1>
            <div>
                {result.results.map((pokemon) => (
                    <Pokemon key={pokemon.name} pokemon={pokemon} />
                ))}
            </div>
        </main>
    )
}
export default App

As you can see, we start by importing useSWR from the SWR library. This declares the URL of the API you want to get data from, and a function to fetch these data.

The function fetcher is used here to transform the data into JSON. It receives the data fetched as an argument and returns something.

Notice that here, I use the Rest operator ((...args)) since I’m not sure of the type and length of data received as a parameter, therefore, I copy everything before passing it again as an argument to the fetch method provided by useSWR which transforms the data into JSON and returns it.

That said, the fetcher and the url of the API can be now passed as parameters to the useSWR hook. With that, it can now make the request and it returns two states: the data fetched and an error state. And data: result is the same as data.result, we use object destructuring to pull result from data.

With the returned values, we can now check if the data is successfully fetched and then loop through it. And for each user, use the Pokemon component to display it.

Now we have the data and pass it down to the Pokemon Component, it’s time to update Pokemon.js to be able to receive and display the data.

Creating The Pokemon Component

import React from 'react'
import useSWR from 'swr'

const fetcher = (...args) => fetch(...args).then((res) => res.json())

export const Pokemon = ({ pokemon }) => {
    const { name } = pokemon
    const url = 'https://pokeapi.co/api/v2/pokemon/' + name

    const { data, error } = useSWR(url, fetcher)

    if (error) return <h1>Something went wrong!</h1>
    if (!data) return <h1>Loading...</h1>

    return (
        <div className='Card'>
            <span className='Card--id'>#{data.id}</span>
            <img
                className='Card--image'
                src={data.sprites.front_default}
                alt={name}
            />
            <h1 className='Card--name'>{name}</h1>
            <span className='Card--details'>
                {data.types.map((poke) => poke.type.name).join(', ')}
            </span>
        </div>
    )
}

Here, we have a component that receives a single Pokemon data from the API and displays it. However, the data received does not contain all fields needed, hence we have to make another request to the API to get the complete Pokemon object.

And as you can see, we use the same process to retrieve the data even if this time we append the name of the Pokemon to the URL.

By the way, if you are not familiar with destructuring, ({ pokemon }) is the same as receiving props and accessing to the pokemon object with props.pokemon. It’s just a shorthand to pull out values from objects or arrays.

With that in place, if you navigate to the root folder of the project and run on the terminal the following command:

yarn start

Or if you’re using npm:

npm start

You should see that the data are successfully fetched from the Pokemon API and displayed as expected.

Great! We are now able to fetch remote data with SWR. However, this setup is a local one and can be a bit redundant because you can already see that App.js and Pokemon.js use the same fetcher function to do the same thing.

But luckily, the package comes with a handy provider named SWRConfig that helps to configure SWR globally. It’s a wrapper component that allows child components to use the global configuration and therefore the fetcher function.

To setup SWR globally, we need to update the index.js file because it’s where the App component is rendered using React DOM. If you want, you can use SWRConfig directly in the App.js file.

Configuring SWR Globally

import React from 'react'
import ReactDOM from 'react-dom'
import { SWRConfig } from 'swr'
import App from './App'
import './index.css'

const fetcher = (...args) => fetch(...args).then((res) => res.json())

ReactDOM.render(
    <React.StrictMode>
        <SWRConfig value={{ fetcher }}>
            <App />
        </SWRConfig>
    </React.StrictMode>,
    document.getElementById('root')
)

As you can see, we start by importing SWRConfig which is a provider that needs to wrap the higher component or just part of your React app that needs to use SWR features. It takes as props a value that expects an object of config. You can pass more than one property to the config object, here I just need the function to fetch data.

Now, instead of declaring the fetcher function in every file, we create it here and pass it as value to SWRConfig. With that, we can now retrieve data at any level in our app without creating another function and hence avoid redundancy.

Besides that, fetcher is equal to fetcher: fetcher, it’s just syntactic sugar proposed by ES6. With that change, we need now to update our components to use the global config.

Using The Global SWR Config

import React from 'react'
import useSWR from 'swr'
import { Pokemon } from './components/Pokemon'

const url = 'https://pokeapi.co/api/v2/pokemon'

function App() {
    const { data: result, error } = useSWR(url)

    if (error) return <h1>Something went wrong!</h1>
    if (!result) return <h1>Loading...</h1>

    return (
        <main className='App'>
            <h1>Pokedex</h1>
            <div>
                {result.results.map((pokemon) => (
                    <Pokemon key={pokemon.name} pokemon={pokemon} />
                ))}
            </div>
        </main>
    )
}
export default App

Now we only need to pass the url to useSWR, instead of passing the url and fetcher method. Let’s also tweak the Pokemon component a bit.

import React from 'react'
import useSWR from 'swr'

export const Pokemon = ({ pokemon }) => {
    const { name } = pokemon
    const url = 'https://pokeapi.co/api/v2/pokemon/' + name

    const { data, error } = useSWR(url)

    if (error) return <h1>Something went wrong!</h1>
    if (!data) return <h1>Loading...</h1>

    return (
        <div className='Card'>
            <span className='Card--id'>#{data.id}</span>
            <img
                className='Card--image'
                src={data.sprites.front_default}
                alt={name}
            />
            <h1 className='Card--name'>{name}</h1>
            <span className='Card--details'>
                {data.types.map((poke) => poke.type.name).join(', ')}
            </span>
        </div>
    )
}

You can already see that we have no fetcher function anymore, thanks to the global configuration which passes the function to useSWR under the hood.

Now, you can use the global fetcher function everywhere in your app. The only thing that the useSWR hook needs to fetch remote data is the URL.

However, we can still enhance the setup furthermore by creating a custom hook to avoid declaring the URL again and again, and instead, just pass as parameter the path.

Advanced Setup By Creating A Custom Hook

To do so, you have to create a new file in the root of the project named useRequest.js (you can name it whatever you want) and add this code block below to it.

import useSwr from 'swr'

const baseUrl = 'https://pokeapi.co/api/v2'

export const useRequest = (path, name) => {
    if (!path) {
        throw new Error('Path is required')
    }

    const url = name ? baseUrl + path + '/' + name : baseUrl + path
    const { data, error } = useSwr(url)

    return { data, error }
}

Here, we have a function that receives a path and optionally a name and appends it to the base URL to build the complete URL. Next, it checks if a name parameter is received or not and handle it consequently.

Then, that URL is passed as a parameter to the useSWR hook to be able to fetch the remote data and return it. And if no path is passed, it throws an error.

Great! we need now to tweak the components a bit to use our custom hook.

import React from 'react'
import { useRequest } from './useRequest'
import './styles.css'
import { Pokemon } from './components/Pokemon'

function App() {
    const { data: result, error } = useRequest('/pokemon')

    if (error) return <h1>Something went wrong!</h1>
    if (!result) return <h1>Loading...</h1>

    return (
        <main className='App'>
            <h1>Pokedex</h1>
            <div>
                {result.results.map((pokemon) => (
                    <Pokemon key={pokemon.name} pokemon={pokemon} />
                ))}
            </div>
        </main>
    )
}
export default App

Now, instead of using the SWR hook, we use the custom hook built on top of it and then pass as expected the path as an argument. With that in place, everything will work like before but with a much cleaner and flexible configuration.

Let’s also update the Pokemon component.

import React from 'react'
import { useRequest } from '../useRequest'

export const Pokemon = ({ pokemon }) => {
    const { name } = pokemon
    const { data, error } = useRequest('/pokemon', name)

    if (error) return <h1>Something went wrong!</h1>
    if (!data) return <h1>Loading...</h1>

    return (
        <div className='Card'>
            <span className='Card--id'>#{data.id}</span>
            <img
                className='Card--image'
                src={data.sprites.front_default}
                alt={name}
            />
            <h1 className='Card--name'>{name}</h1>
            <span className='Card--details'>
                {data.types.map((poke) => poke.type.name).join(', ')}
            </span>
        </div>
    )
}

You can already see how our custom hook makes things easier and more flexible. Here, we just need to pass additionally the name of the Pokemon to fetch to useRequest and it handles everything for us.

I hope you start enjoying this cool library — However, we still have things to discover because SWR offers so many features, and one of them is useSWRPages which is a hook to paginate data easily. So, let’s use that hook in the project.

Paginate Our Data With useSWRPages

SWR allows us to paginate data easily and request only a part of it, and when needed refetch data to show for the next page.

Now, let’s create a new file in the root of the project usePagination.js and use it as a custom hook for pagination.

import React from 'react'
import useSWR, { useSWRPages } from 'swr'
import { Pokemon } from './components/Pokemon'

export const usePagination = (path) => {
    const { pages, isLoadingMore, loadMore, isReachingEnd } = useSWRPages(
        'pokemon-page',
        ({ offset, withSWR }) => {
            const url = offset || `https://pokeapi.co/api/v2${path}`
            const { data: result, error } = withSWR(useSWR(url))

            if (error) return <h1>Something went wrong!</h1>
            if (!result) return <h1>Loading...</h1>

            return result.results.map((pokemon) => (
                <Pokemon key={pokemon.name} pokemon={pokemon} />
            ))
        },
        (SWR) => SWR.data.next,
        []
    )

    return { pages, isLoadingMore, loadMore, isReachingEnd }
}

As you can see, here we start by importing useSWRPages which is the helper that allows paginating data easily. It receives 4 arguments: the key of the request pokemon-page which is also used for caching, a function to fetch the data that returns a component if the data are successfully retrieved, and another function that takes the SWR object and request data from the next page, and an array of dependencies.

And once the data fetched, the function useSWRPages returns several values, but here we need 4 of them: the pages that is the component returned with the data, the function isLoadingMore which checks if the data are currently fetched, the function loadMore that helps fetching more data, and the method isReachingEnd which determines whether there is still data to retrieve or not.

Now we have the custom hook that returns the needed values to paginate data, we can now move to the App.js file and tweak it a bit.

import React from 'react'
import { usePagination } from './usePagination'
import './styles.css'

export default function App() {
    const { pages, isLoadingMore, loadMore, isReachingEnd } = usePagination(
        '/pokemon'
    )

    return (
        <main className='App'>
            <h1>Pokedex</h1>
            <div>{pages}</div>
            <button
                onClick={loadMore}
                disabled={isLoadingMore || isReachingEnd}
            >
                Load more...
            </button>
        </main>
    )
}

Once the usePagination hook imported, we can now pass the path as a parameter and get back the returned values. And since pages is a component, we don’t need to loop through the data or anything like that.

Next, we use the function loadMore on the button to fetch more data and disable it if the retrieving operation is not finished or if there is no data to fetch.

Great! with that change, we can now browse on the root of the project and start the server with this command to preview our app.

yarn start

Or if you’re using npm:

npm start

You should see that the data are successfully fetched and if you click on the button, new data will be retrieved by SWR

So far, we have seen in practice the SWR library, and I hope you are finding value on it. However, it still has some features to offer. Let’s dive into these functionalities in the next section.

Other Features Of SWR

The SWR library has a bunch of handy things that simplifies the way we build React apps.

Focus Revalidation

It’s a feature that allows updating or revalidating to be precise the data when you re-focus a page or switch between tabs. And by default, this functionality is enabled, but you can disable it anyway if it does not fit your need. It can be useful especially if you have data with high-level-frequency updates.

Refetch on Interval

The SWR library allows refetching data after a certain amount of time. It can be handy when your data changes at high speed or you need to make a new request to get a piece of new information from your database.

Local Mutation

With SWR, you can set a temporary local state that will update automatically when new data are fetched(revalidation). This feature comes in play particularly when you deal with an Offline-first approach, it helps to update data easily.

Scroll Position Recovery

This feature is very handy, especially when it comes to dealing with huge lists. It allows you to recover the scroll position after getting back to the page. And in any case, it increases the usability of your app.

Dependent Fetching

SWR allows you to fetch data that depends on other data. That means it can fetch data A, and once that operation is done, it uses it to fetch data B while avoiding waterfalls. And this feature helps when you have relational data.

That said, SWR helps to increase the user experience in any matter. It has more features than that, and for many cases it’s better to use it over the Fetch API or the Axios library.

Conclusion

Throughout this article, we have seen why SWR is an awesome library. It allows remote data fetching using React Hooks and helps to simplify some advanced features out of the box such as pagination, caching data, refetching on interval, scroll position recovery, and so on. SWR is also backend agnostic which means it can fetch data from any kind of APIs or databases. In definitive, SWR increases a lot the user experience of your React apps, it has a bright future and you should keep an eye on it or better use it in your next React app.

You can preview the finished project live here.

Thanks for reading!

Next Steps

You can go on to check the following links which will give you a better understanding beyond the scope of this tutorial.

 

 

 

Wednesday, September 16, 2020

Do you know how the stuff will be done for Checkout Customization on BigCommerce

 

It’s no surprise that the checkout page is where the magic happens on an ecommerce site. And as an ecommerce developer, you know that the requirements for the checkout design can vary widely from business to business.

At BigCommerce, we’ve put a lot of research behind our flagship checkout page, Optimized One-Page Checkout, and it’s designed to create a checkout experience that will streamline the purchase process and increase conversions for merchants across the platform. But we also recognize that there’s no one size fits all solution. Across verticals and business models, there’s a ton of variation in merchants’ design needs and the experience their shoppers expect when they proceed to checkout.

The ability to customize the appearance and functionality of the checkout page is essential, especially for developers who support enterprise businesses. Our philosophy is that merchants should be able to look to the Optimized One-Page Checkout as an example of best practices in checkout form design, but we also want to build as much openness into our checkout as possible to accommodate merchants with specific business needs who are able to take on the effort of advanced customization.

This guide will outline the breadth of checkout customization options on BigCommerce, from no-code or low-code customizations all the way to complex headless builds. We’ll begin with a technical overview of the BigCommerce checkout page and then walk through the spectrum of customization options available for the checkout page, from native settings to defining every pixel of the checkout.

Special Considerations

Let’s start by establishing the fact that customizing the checkout page is different than customizing other default templates in your theme. Although there are many good reasons for customizing the checkout page, the consequences of introducing bugs are significant. Anything that affects checkout page uptime is going to have a direct impact on a store’s sales.

Security is also a consideration. One of the big advantages of using a platform like BigCommerce is that PCI compliance is bundled into the core feature set when using the native checkout page. PCI refers to the Payment Card Industry Data Security Standard, and it governs the way companies who handle credit card information maintain a secure environment. PCI compliance reaches into many areas: infrastructure, engineering, even the practices of company employees. At BigCommerce, we go to great lengths to make sure our platform meets these security standards.

Some types of checkout customizations affect BigCommerce’s ability to assume the burden of PCI compliance and shift this responsibility to the party customizing the checkout. For example, an app that injects JavaScript into the checkout page or a headless checkout that’s hosted on an external server would be within PCI scope.

That being said, there are best practices you can follow to make sure that the custom code you apply to the checkout page is going to play nicely with the platform — today and across future updates. We’ll cover a few of those best practices in this blog post. Full guidelines on PCI compliance are out of the scope of this post, but you can read more on requirements here (Developer Portal).

Technical Overview

The Optimized One-page Checkout is a single page application whose purpose is to convert a Cart to an Order. The checkout application is made up of several layers:

  • Backend application

The Optimized One-page checkout consumes the same Storefront Checkout API and JS SDK that are available to external developers. The Storefront Checkout API surfaces the business logic of the backend ecommerce application — retrieving customer information, fetching available shipping methods, and calculating discounts and sales tax. The JS SDK is a wrapper library that provides methods for interacting with the Storefront Checkout API.

The process for converting a cart to an order follows this flow:

  1. A Cart object begins as a collection of product line items and a customer account ID. It becomes a Checkout object when it picks up additional data — a billing and shipping address — that provide enough context to calculate discounts, taxes, and shipping options.

Although there is quite a bit of flexibility in what you can customize on the checkout page, there’s one important thing to keep in mind. The application logic that backs the Checkout API has certain validations and rules in place around the checkout flow that will still need to be followed, even if you change the UI. For example, a Checkout object must always have an email address associated with it, and if the cart contains physical products, a shipping address.

In most cases, the flow for a custom checkout will still map to the customer experience outlined above, but there may be edge cases that require a different sequence. It’s possible to create a presentation layer in the UI that makes it seem as though you are bypassing required fields (for example, by masking the fields and filling them with dummy data), but you’ll need to handle that logic within your customizations to process orders successfully. Lastly, the checkout customizations detailed here do not allow you to change the underlying functionality of the checkout, for example, by integrating an unsupported payment method.

Available Customization Options

In this section, we’ll start with the lightest lift and talk about a few of the customization options that are built into the BigCommerce Control Panel. Then, we’ll talk about how you can customize the text that appears on the checkout page, and even translate it into another language. Finally, we’ll go over how to add custom styling and functionality to the checkout with CSS and JavaScript.

1. Checkout Form Fields.

BigCommerce natively supports the ability to define new fields on the checkout page address form as well as reordering fields. Custom fields will be visible to the shopper on the checkout page and the values the shopper fills in will be visible in the Order View section of the Control Panel. Custom address fields support a variety of input types: checkbox, text field, date picker, dropdown, number-only, and password.

Common uses for custom checkout form fields include things like collecting a customer’s account number or verifying a delivery preference. Because custom address fields do persist to the Order View screen, developers making advanced customizations can repurpose custom form fields to store data that needs to be carried over to the Order record.

2. Store Design Settings

Another native option for styling the checkout page is Store Design. The Store Design editor provides an interface for controlling settings like the checkout page’s header image, colors, and fonts. It’s always a good idea to check for a setting before hard-coding CSS, because it gives merchants more control over their design and ensures their choices persist through theme updates.

As a theme developer, you can control which Store Design settings are available for merchants to configure. Settings, along with their possible values, are defined in the theme’s schema.json file, and current selected values are stored in config.json, which can be referenced by custom Sass functions. For more on developing Store Design settings, visit our documentation.

3. Multi-language checkout.

Moving on to customizations that require light custom code, the text strings that display on the Optimized One-page Checkout page can be edited, or even translated into multiple languages.

The checkout page follows the same convention used by all Stencil templates to render text strings. The {{lang}} helper, custom to Stencil, pulls a text string’s value from a set of JSON files, based on the language setting detected in the shopper’s browser. A store can have multiple .json lang files, one for each language that a store supports.

To access the translation keys that are rendered on the checkout page, you’ll need to append a JSON object containing the checkout keys and their text string values to your store’s .json lang file(s). If English is the default language on your store but you wish to change the wording on some of the checkout fields, you would add the checkout JSON object to the en.json file; if your store supports English and French and you wish to show a French version of the checkout page to French-speaking shoppers, you would add the checkout JSON object to your fr.json file and translate the key values accordingly.

4. Custom CSS.

The Optimized One-page Checkout references the optimized-checkout.scss file for styling, and you can review our theme documentation for a list of CSS classes that are applied to checkout elements. It’s important to note that you don’t want to nest or alter the built in class names, because it can break compatibility with future checkout page updates. Beyond that, you have the ability to reference a custom stylesheet or add your own CSS rules to manipulate styles and layout.

5. Custom JavaScript.

BigCommerce supports checkout page script injection via the Script Manager, an interface for managing third party scripts. If you’re building an app and need to run custom JavaScript on the checkout or order confirmation page, to create a pop-up for example, you can also inject scripts programmatically using the Scripts API.

The accordion layout of the Optimized One-page checkout loads dynamically as the shopper proceeds through the steps, which is something you’ll want to consider to make sure that your JavaScript is executing at the right time. While you could poll the DOM using setInterval() to make sure the element you want to target has loaded, using Mutation Observer is a nice, clean alternative. Support for Mutation Observer is built into modern browsers, so there’s no need to bring in a dependency to use it.

As an example, let’s say we want to execute some JavaScript on the Billing Address step of the checkout process. We could do the following, which checks for an element with the ID #checkoutBillingAddress. (adapted from Ryan Morr’s blog post)

Mutation Observer listening for Billing Address step

Note: While our engineering team is mindful of keeping DOM elements and classes consistent, we cannot guarantee that element IDs will never change across future updates. The best practice for running custom scripts on the checkout page is to avoid interacting with the checkout code directly, and these instructions are provided as a consideration for developers who have weighed the risk.

Headless Checkout

Now that we’ve covered some of the standard customizations you might want to make to checkout, let’s get into the more advanced options. BigCommerce surfaces APIs that cover the full checkout process end-to-end, which means that you can build a fully custom checkout either on top of the native storefront, or on a remote platform.

First, let’s set a quick baseline for what we mean by “headless checkout.”

Headless means that the front-end presentation layer has been decoupled from the backend platform that powers it. Remember when we talked about the layers that make up the Optimized One-page checkout? When you’re building a headless checkout, you’re still leveraging the backend application logic that’s surfaced through the API, but you replace the frontend presentation layer — or “head” — with a UI that’s purpose-built to your design needs and technology preferences.

You have several options for building decoupled checkouts, and the right choice for the job will depend on the level of control that you need, your ability to take on advanced development and security compliance, and the domain on which you need to run the checkout. We’ll talk through those considerations below.

1. Checkout JS SDK.

The BigCommerce Checkout JS SDK is a wrapper library for the Storefront Checkout API, which is the same API that powers the native checkout page. You can use the Checkout SDK to call methods on the Storefront Checkout API to move the shopper through the purchase process.

The Checkout SDK is a tool for building a custom UI for the checkout page, on the BigCommerce store domain. Essentially, it allows you to build a checkout UI replacement on BigCommerce.

The frontend technology that you use to build your custom checkout page is entirely up to you — you could use React or Vue, or even vanilla JavaScript or jQuery. This gives you a great deal of freedom to build highly customized checkout experiences, including features like a local pickup or delivery step or other add-ons.

So how does the Checkout SDK relate to the concept of headless checkout? Checkout pages built with the SDK are considered headless because you’re replacing the native presentation layer with one that’s custom-built on another framework. The Checkout SDK can also provide a checkout solution for remote headless storefronts, if you redirect back to the BigCommerce domain for the checkout step. This can be a good option if you need a great deal of control over the checkout look-and-feel, but want to reduce the overhead of building a remote checkout completely from scratch.

2. Embedded Checkout.

Embedded Checkout is a version of the Optimized One-page checkout that can be iframed into an external website, like a CMS. Embedded checkout is a great solution for a remote headless storefront, because shoppers can complete their purchase in-context, without being redirected to a BigCommerce domain.

The advantage of Embedded Checkout is that it limits the PCI scope taken on by the developer. Because the checkout page is on the BigCommerce domain and isn’t modified by external code, BigCommerce PCI compliance can extend to the remote storefront’s checkout. That built-in security comes with a few trade offs when it comes to how much the checkout page can be customized. Some styling options are available, allowing you to customize things like colors and font sizes, but the ability to inject custom CSS or JavaScript is limited.

Today, embedded checkout is coupled to the BigCommerce for WordPress plugin, but soon we’ll be releasing documentation on using embedded checkout with a wider range of CMSs and external storefronts. Stay tuned!

3. Server-to-Server Checkout API.

The Server-to-Server (S2S) Checkout API allows developers to orchestrate a checkout on a remote server. This means that developers can leverage the BigCommerce backend business logic to convert a cart to an order, external to the BigCommerce storefront.

To understand how the S2S Checkout API contrasts with other headless checkout options, let’s compare it to the Checkout SDK and embedded checkout. The Checkout SDK allows you to have a high degree of control over presentation, but it must be used on the native storefront. Embedded checkout allows you to use the BigCommerce checkout on a remote storefront easily and securely, but it gives you less control over the checkout page presentation. The S2S Checkout API allows you to build your checkout on a remote storefront, and it gives you complete control over the presentation.

The S2S Checkout API provides maximum flexibility both in terms of presentation and context. You can use the S2S checkout API to build a checkout page on a remote storefront, mobile app, or other checkout experience, like a kiosk. Along with that flexibility comes a heavier development lift, and because you are building and hosting the form that will accept credit card information, responsibility for making sure the checkout is PCI compliant.

Conclusion

BigCommerce offers a wide range of options for customizing the checkout page — everything from settings that can be adjusted from within the control panel, to completely custom-built headless checkout pages. In this blog post, we’ve surveyed a number of those options, including:

  • Custom Address Form Fields
No matter which checkout customization option you choose, be sure to visit our Developer Portal for detailed documentation on the features mentioned here.

Friday, August 7, 2020

Higher-Order Components In React

In this tutorial, we are going to learn about higher-order components, the syntax of higher-order components, as well as use cases for them. In the process, we will build a higher-order component from an existing React component. By the end of this tutorial, you will understand the basics of higher-order components and how to build them.
Higher-order components (HOCs) in React were inspired by higher-order functions in JavaScript. A HOC is an advanced technique for reusing logic in React components. It is a pattern created out of React’s compositional nature.
HOCs basically incorporate the don’t-repeat-yourself (DRY) principle of programming, which you’ve most likely come across at some point in your career as a software developer. It is one of the best-known principles of software development, and observing it is very important when building an application or writing code in general.
In this tutorial, we will learn what a HOC is, its basic structure, some use cases, and finally an example.
Note: Basic knowledge of React and JavaScript will come in handy as you work through this tutorial.

Higher-Order Functions In JavaScript

Before jumping into HOCs in React, let’s briefly discuss higher-order functions in JavaScript. Understanding them is critical to understanding our topic of focus.
Higher-order functions in JavaScript take some functions as arguments and return another function. They enable us to abstract over actions, not just values, They come in several forms, and they help us to write less code when operating on functions and even arrays.
The most interesting part of using higher-order functions is composition. We can write small functions that handle one piece of logic. Then, we can compose complex functions by using the different small functions we have created. This reduces bugs in our code base and makes our code much easier to read and understand.
JavaScript has some of these functions already built in. Some examples of higher-order functions are the following:
  • .forEach()
    This iterates over every element in an array with the same code, but does not change or mutate the array, and it returns undefined.
  • .map()
    This method transforms an array by applying a function to all of its elements, and then building a new array from the returned values.
  • .reduce()
    This method executes a provided function for each value of the array (from left to right).
  • .filter()
    This checks every single element in an array to see whether it meets certain criteria as specified in the filter method, and then it returns a new array with the elements that match the criteria.
So many higher-order functions are built into JavaScript, and you can make your own custom ones.

An Example Of Custom Higher-Order Function

Suppose we are asked to write a function that formats integers as currencies, including some customization of specifying the currency symbol and adding a decimal separator for the currency amount. We can write a higher-other function that takes the currency symbol and also the decimal separator. This same function would then format the value passed to it with the currency symbol and decimal operators. We would name our higher-order function formatCurrency.
const formatCurrency = function( 
    currencySymbol,
    decimalSeparator  ) {
    return function( value ) {
        const wholePart = Math.trunc( value / 100 );
        let fractionalPart = value % 100;
        if ( fractionalPart < 10 ) {
            fractionalPart = '0' + fractionalPart;
        }
        return `${currencySymbol}${wholePart}${decimalSeparator}${fractionalPart}`;
    }
}
formatCurrency returns a function with a fixed currency symbol and decimal separator.
We then pass the formatter a value, and format this value with the function by extracting its whole part and the fractional part. The returned value of this function is constructed by a template literal, concatenating the currency symbol, the whole part, the decimal separator, and the fractional part.
Let’s use this higher-order function by assigning a value to it and seeing the result.
> getLabel = formatCurrency( '$', '.' );
 
> getLabel( 1999 )
"$19.99" //formatted value
 
> getLabel( 2499 )
"$24.99" //formatted value
You might have noticed that we created a variable named getLabel, then assigned our formatCurrency higher-order function, and then passed the currency formatters to the function, which is the currency symbol and a decimal separator. To make use of the function, we call getLabel, which is now a function, and we pass in the value that needs to be formatted. That’s all! We have created a custom higher order of our choice.

What Is A Higher-Order Component?

A higher-order component (HOC) is an advanced element for reusing logic in React components. Components take one or more components as arguments, and return a new upgraded component. Sounds familiar, right? They are similar to higher-order functions, which take some functions as an argument and produce a new function.
HOCs are commonly used to design components with certain shared behavior in a way that makes them connected differently than normal state-to-props pattern.

Facts About HOCs

  1. We don’t modify or mutate components. We create new ones.
  2. A HOC is used to compose components for code reuse.
  3. A HOC is a pure function. It has no side effects, returning only a new component.
Here are some examples of real-world HOCs you might have come across:
react-reduxconnect(mapStateToProps, mapDispatchToProps)(UserPage)
react-routerwithRouter(UserPage)
material-uiwithStyles(styles)(UserPage)

Structure Of A Higher-Order Component

A HOC is structured like a higher-order function:
  • It is a component.
  • It takes another component as an argument.
  • Then, it returns a new component.
  • The component it returns can render the original component that was passed to it.
The snippet below shows how a HOC is structured in React:

import React from 'react';
// Take in a component as argument WrappedComponent
const higherOrderComponent = (WrappedComponent) => {
// And return another component
  class HOC extends React.Component {
    render() {
      return <WrappedComponent />;
    }
  }
  return HOC;
};
We can see that higherOrderComponent takes a component (WrappedComponent) and returns another component inside of it. With this technique, whenever we need to reuse a particular component’s logic for something, we can create a HOC out of that component and use it wherever we like.

Use Cases

In my experience as a front-end engineer who has been writing React for a while now, here are some use cases for HOCs.
Show a loader while a component waits for data
Most of the time, when building a web application, we would need to use a loader of some sort that is displayed while a component is waiting for data to be passed to its props. We could easily use an in-component solution to render the loader, which would work, but it wouldn’t be the most elegant solution. Better would be to write a common HOC that can track those props; and while those props haven’t been injected or are in an empty state, it can show a loading state.
To explain this properly, let’s build a list of categories of public APIs, using its open API. We tend to handle list-loading, so that our clients don’t panic when the API we are getting data from takes so much time to respond.
Let’s generate a React app:
npx create-react-app repos-list
A basic list component can be written as follows:
//List.js
import React from 'react';
const List = (props) => {
  const { repos } = props;
  if (!repos) return null;
  if (!repos.length) return <p>No repos, sorry</p>;
  return (
    <ul>
      {repos.map((repo) => {
        return <li key={repo.id}>{repo.full_name}</li>;
      })}
    </ul>
  );
};
export default List;
The code above is a list component. Let’s break down the code into tiny bits so that we can understand what is happening.
const List = (props) => {};
Above, we initialize our functional component, named List, and pass props to it.
const { repos } = props;
Then, we create a constant, named repos, and pass it to our component props, so that it can be used to modify our component.
if (!repos) return null;
if (!repos.length) return <p>No repos, sorry</p>;
Above, we are basically saying that, if after fetching has completed and the repos prop is still empty, then it should return null. We are also carrying out a conditional render here: If the length of the repos prop is still empty, then it should render “No repos, sorry” in our browser.
return (
    <ul>
      {repos.map((repo) => {
        return <li key={repo.id}>{repo.full_name}</li>;
      })}
    </ul>
  );
Here, we are basically mapping through the repos array and returning a list of repos according to their full names, with a unique key for each entry.
Now, let’s write a HOC that handles loading, to make our users happy.
//withdLoading.js
import React from 'react';
function WithLoading(Component) {
  return function WihLoadingComponent({ isLoading, ...props }) {
    if (!isLoading) return <Component {...props} />;
    return <p>Hold on, fetching data might take some time.</p>;
  };
}
export default WithLoading;
This would display the text “Hold on, fetching data might take some time” when the app is still fetching data and the props are being injected into state. We make use of isLoading to determine whether the component should be rendered.
Now, in your App.js file, you could pass the loading logic to WithLoading, without worrying about it in your List .
import React from 'react';
import List from './components/List.js';
import WithLoading from './components/withLoading.js';
const ListWithLoading = WithLoading(List);
class App extends React.Component {
  state = {
{
  };
  componentDidMount() {
    this.setState({ loading: true });
    fetch(`https://api.github.com/users/hacktivist123/repos`)
      .then((json) => json.json())
      .then((repos) => {
        this.setState({ loading: false, repos: repos });
      });
  }
  render() {
    return (
      <ListWithLoading
        isLoading={this.state.loading}
        repos={this.state.repos}
      />
    );
  }
}
export default App;
The code above is our entire app. Let’s break it down to see what is happening.
class App extends React.Component {
  state = {
    loading: false,
    repos: null,
  };
  componentDidMount() {
    this.setState({ loading: true });
    fetch(`https://api.github.com/users/hacktivist123/repos`)
      .then((json) => json.json())
      .then((repos) => {
        this.setState({ loading: false, repos: repos });
      });
  }
All we are doing here is creating a class component named App(), then initializing state with two properties, loading: false, and repos: null,. The initial state of loading is false, while the initial state of repos is also null.
Then, when our component is mounting, we set the state of the loading property to true, and immediately make a fetch request to the API URL that holds the data we need to populate our List component. Once the request is complete, we set the loading state to false and populate the repos state with the data we have pulled from the API request.
const ListWithLoading = WithLoading(List);
Here, we create a new component named ListWithLoading and pass the WithLoading HOC that we created and also the List component in it.
render() {
    return (
      <ListWithLoading
        isLoading={this.state.loading}
        repos={this.state.repos}
      />
    );
  }
Above, we render the ListWithLoading component, which has been supercharged by the WithLoading HOC that we created and also the List component in it. Also, we pass the loading state’s value and the repos state’s value as props to the component.

Conditionally Render Components

Suppose we have a component that needs to be rendered only when a user is authenticated — it is a protected component. We can create a HOC named WithAuth() to wrap that protected component, and then do a check in the HOC that will render only that particular component if the user has been authenticated.
A basic withAuth() HOC, according to the example above, can be written as follows:
// withAuth.js
import React from "react";
export function withAuth(Component) {
    return class AuthenticatedComponent extends React.Component {
        isAuthenticated() {
            return this.props.isAuthenticated;
        }

        /**
         * Render
         */
        render() {
            const loginErrorMessage = (
                <div>
                    Please <a href="/login">login</a> in order to view this part of the application.
                </div>
            );

            return (
                <div>
                    { this.isAuthenticated === true ? <Component {...this.props} /> : loginErrorMessage }
                </div>
            );
        }
    };
}

export default withAuth;
The code above is a HOC named withAuth. It basically takes a component and returns a new component, named AuthenticatedComponent, that checks whether the user is authenticated. If the user is not authenticated, it returns the loginErrorMessage component; if the user is authenticated, it returns the wrapped component.
Note: this.props.isAuthenticated has to be set from your application’s logic. (Or else use react-redux to retrieve it from the global state.)
To make use of our HOC in a protected component, we’d use it like so:
// MyProtectedComponent.js
import React from "react";
import {withAuth} from "./withAuth.js";

export class MyProectedComponent extends React.Component {
    /**
     * Render
     */
    render() {
        return (
            <div>
                This is only viewable  by authenticated users.
            </div>
        );
    }
}

// Now wrap MyPrivateComponent with the requireAuthentication function 
export default withAuth(MyPrivateComponent);
Here, we create a component that is viewable only by users who are authenticated. We wrap that component in our withAuth HOC to protect the component from users who are not authenticated.

Provide Components With Specific Styling

Continuing the use case above, based on whatever UI state you get from the HOC, you can render specific styles for specific UI states. For example, if the need arises in multiple places for styles like backgroundColor, fontSize and so on, they can be provided via a HOC by wrapping the component with one that just injects props with the specific className.
Take a very simple component that renders “hello” and the name of a person. It takes a name prop and some other prop that can affect the rendered JavaScript XML (JSX).
// A simple component 
const HelloComponent = ({ name, ...otherProps }) => (
 <div {...otherProps}>Hello {name}!/div>
);
Let’s create a HOC named withStyling that adds some styling to the “hello” text.
const withStyling = (BaseComponent) => (props) => (
  <BaseComponent {...props} style={{ fontWeight: 700, color: 'green' }} />
);
In order to make use of the HOC on our HelloComponent, we wrap the HOC around the component. We create a pure component, named EnhancedHello, and assign the HOC and our HelloComponent, like so :
const EnhancedHello = withStyling(HelloComponent);
To make a change to our HelloComponent, we render the EnhancedHello component:
<EnhancedHello name='World' />
Now, the text in our HelloComponent becomes this:
<div style={{fontWeight: 700, color: 'green' }}>Hello World</div>

Provide A Component With Any Prop You Want

This is a popular use case for HOCs. We can study our code base and note what reusable prop is needed across components. Then, we can have a wrapper HOC to provide those components with the reusable prop.
Let’s use the example above:
// A simple component 
const HelloComponent = ({ name, ...otherProps }) => (
 <div {...otherProps}>Hello {name}!</div>
);
Let’s create a HOC named withNameChange that sets a name prop on a base component to “New Name”.
const withNameChange = (BaseComponent) => (props) => (
  <BaseComponent {...props} name='New Name' />
);
In order to use the HOC on our HelloComponent, we wrap the HOC around the component, create a pure component named EnhancedHello2, and assign the HOC and our HelloComponent like so:
const EnhancedHello2 = withNameChange(HelloComponent);
To make a change to our HelloComponent, we can render the EnhancedHello component like so:
<EnhancedHello />
Now, the text in our HelloComponent becomes this:
<div>Hello New World</div>
To change the name prop, all we have to do is this:
<EnhancedHello name='Shedrack' />
The text in our HelloComponent becomes this:
<div>Hello Shedrack</div>

Let’s Build A Higher-Order Component

In this section, we will build a HOC that takes a component that has a name prop, and then we will make use of the name prop in our HOC.
So, generate a new React app with create-react-app, like so:
npx create-react-app my-app
After it is generated, replace the code in your index.js file with the following snippet.
import React from 'react';
import { render } from 'react-dom';
const Hello = ({ name }) =>
  <h1>
    Hello {name}!
  </h1>;

function withName(WrappedComponent) {
  return class extends React.Component {
    render() {
      return <WrappedComponent name="Smashing Magazine" {...this.props} />;
    }
  };
}
const NewComponent = withName(Hello);
const App = () =>
  <div>
    <NewComponent />
  </div>;
render(<App />, document.getElementById('root')); 
 
 
Let’s go through the snippet bit by bit.
const Hello = ({ name }) =>
  <h1>
    Hello {name}!
  </h1>;
Here, we create a functional component that has a prop called name. In this functional component, we render the “Hello” and the value of the name prop in an h1 tag.
function withName(WrappedComponent) {
  return class extends React.Component {
    render() {
      return <WrappedComponent name="Smashing Magazine" {...this.props} />;
    }
  };
}
Above, we create a higher-order functional component named withName(). Then, we return an anonymous class component inside that renders the component wrapped in the HOC. And we assign a value to the prop of the wrapped component.
const NewComponent = withName(Hello);
Here, we create a new component named NewComponent. We use the HOC that we created, and assign to it the functional component that we created at the start of the code base, named hello.
const App = () =>
  <div>
    <NewComponent />
  </div>;
render(<App />, document.getElementById('root'));
All we are doing above is creating another functional component, named App. It renders the NewComponent that we upgraded with our HOC in a div. Then, we use the react-dom function render to display the component in the browser.
That’s all we need to do! Our withName function takes a component as an argument and returns a HOC. A few months from now, if we decide to change things around, we only have to edit our HOC.

Conclusion

I hope you’ve enjoyed working through this tutorial. You can read more about higher-order components in the references listed below. If you have any questions, leave them in the comments section below. I’ll be happy to answer every one.

Resources And References