Problem

React projects are challenging to create and configure from scratch. Not only are there numerous design choices to make—which libraries to include, which tools to use, which language features to enable—but manually created applications will, by their nature, differ from one another. Project idiosyncrasies increase the time it takes a new developer to become productive.

Solution

create-react-app is a tool for building SPAs with a standard structure and a good set of default options. Generated projects use the React Scripts library to build, test, and run the code. Projects have a standard Webpack configuration and a standard set of language features enabled.

Any developer who has worked on one create-react-app application instantly feels at home with any other. They understand the project structure and know which language features they can use. It is simple to use and contains all the features that a typical application requires: from Babel configuration and file loaders to testing libraries and a development server.

If you’re new to React, or need to create a generic SPA with the minimum of fuss, then you should consider creating your app with create-react-app.

You can choose to install the create-react-app command globally on your machine, but this is now discouraged. Instead, you should create a new project by calling create-react-app via npx. Using npx ensures you’re building your application with the latest version of create-react-app:

$ npx create-react-app my-app

This command creates a new project directory called my-app. By default, the application uses JavaScript. If you want to use TypeScript as your development language, create-react-app provides that as an option:

$ npx create-react-app --template typescript my-app

Facebook developed create-react-app, so it should come as no surprise that if you have the yarn package manager installed, then your new project will use yarn by default. To use npm, you can either specify the --use-npm flag or change into the directory and remove the yarn.lock file and then rerun the install with npm:

$ cd my-app
$ rm yarn.lock
$ npm install

To start your application, run the start script:

$ npm start # or yarn start

This command launches a server on port 3000 and opens a browser at the home page, as shown in Figure 1-1.

Figure 1-1. The generated front page

The server delivers your application as a single, large bundle of JavaScript. The code mounts all of its components inside this <div/> in public/index.html:

<div id="root"></div>

The code to generate the components begins in the src/index.js file (src/index.tsx if you’re using TypeScript):

import React from 'react'
import ReactDOM from 'react-dom'
import './index.css'
import App from './App'
import reportWebVitals from './reportWebVitals'

ReactDOM.render(
  <React.StrictMode>
    <App />
  </React.StrictMode>,
  document.getElementById('root')
)

// If you want to start measuring performance in your app, pass a function
// to log results (for example: reportWebVitals(console.log))
// or send to an analytics endpoint. Learn more: https://bit.ly/CRA-vitals
reportWebVitals()

This file does little more than render a single component called <App/>, which it imports from App.js (or App.tsx) in the same directory:

import logo from './logo.svg'
import './App.css'

function App() {
  return (
    <div className="App">
      <header className="App-header">
        <img src={logo} className="App-logo" alt="logo" />
        <p>
          Edit <code>src/App.js</code> and save to reload.
        </p>
        <a
          className="App-link"
          href="https://reactjs.org"
          target="_blank"
          rel="noopener noreferrer"
        >
          Learn React
        </a>
      </header>
    </div>
  )
}

export default App

If you edit this file while the application is start-ed, the page in the browser automatically updates.

When you’re ready to ship the code to production, you need to generate a set of static files that you can deploy on a standard web server. To do this, run the build script:

$ npm run build

The build script creates a build directory and then publishes a set of static files (see Figure 1-2).

Figure 1-2. The generated contents in the build directory

The build copies many of these files from the public/ directory. The code for the app is transpiled into browser-compatible JavaScript and stored in one or more files in the static/js directory. Stylesheets used by the application are stitched together and stored in static/css. Several of the files have hashed IDs added to them so that when you deploy your application, browsers download the latest code rather than some old cached version.

Discussion

create-react-app is not just a tool for generating a new application but also a platform to keep your React application up-to-date with the latest tools and libraries. You can upgrade the react-scripts library as you would any other: by changing the version number and rerunning npm install. You don’t need to manage a list of Babel plugins or postcss libraries, or maintain a complex webpack.config.js file. The react-scripts library manages them all for you.

The configuration is all still there, of course, but buried deep within the react-scripts directory. In there, you will find the webpack.config.js file, containing all the Babel configuration and file loaders that your application will use. Because it’s a library, you can update React Scripts just as you would any other dependency.

If, however, you later decide to manage all of this yourself, you’re free to do so. If you eject the application, then everything comes back under your control:

$ npm run eject

However, this is a one-time-only change. Once you have ejected your application, there is no going back. You should think carefully before ever ejecting an application. You may find that the configuration you need is already available. For example, developers would often eject an application to switch to using TypeScript. The --template typescript option now removes the need for that.

Another common reason for ejecting was to proxy web services. React apps often need to connect to some separate API backend. Developers used to do this by configuring Webpack to proxy a remote server through the local development server. You can now avoid doing this by setting a proxy in the package.json file:

"proxy": "http://myapiserver",

If your code now contacts a URL that the server cannot find locally (/api/thing), the react-scripts automatically proxies these requests to http://myapiserver/api/thing.

You can download the source for this recipe in JavaScript or TypeScript from the GitHub site.

Problem

Content-rich sites like blogs and online stores need to serve large amounts of complex content efficiently. A tool like create-react-app is not suitable for this kind of website because it delivers everything as a single large bundle of JavaScript that a browser must download before anything displays.

Solution

If you are building a content-rich site, consider using Gatsby.

Gatsby focuses on loading, transforming, and delivering content in the most efficient way possible. It can generate static versions of web pages, which means that the response times of Gatsby sites are often significantly slower than, say, those built with create-react-app.

Gatsby has many plugins that can load and transform data efficiently from static local data, GraphQL sources, and third-party content management systems such as WordPress.

You can install gatsby globally, but you can also run it via the npx command:

$ npx gatsby new my-app

The gatsby new command creates a new project in a subdirectory called my-app. The first time you run this command, it asks which package manager to use: either yarn or npm.

To start your application, change into the new directory and run it in development mode:

$ cd my-app
$ npm run develop

You can then open your application at http://localhost:8000, as shown in Figure 1-3.

Figure 1-3. Gatsby page at http://localhost:8000

Gatsby projects have a straightforward structure, as shown in Figure 1-4.

Figure 1-4. The Gatsby directory structure

The core of the application lives under the src directory. Each page within a Gatsby app has its own React component. This is the front page of the default application in index.js:

import * as React from "react"
import { Link } from "gatsby"
import { StaticImage } from "gatsby-plugin-image"

import Layout from "../components/layout"
import Seo from "../components/seo"

const IndexPage = () => (
  <Layout>
    <Seo title="Home" />
    <h1>Hi people</h1>
    <p>Welcome to your new Gatsby site.</p>
    <p>Now go build something great.</p>
    <StaticImage
      src="../images/gatsby-astronaut.png"
      width={300}
      quality={95}
      formats={["AUTO", "WEBP", "AVIF"]}
      alt="A Gatsby astronaut"
      style={{ marginBottom: `1.45rem` }}
    />
    <p>
      <Link to="/page-2/">Go to page 2</Link> <br />
      <Link to="/using-typescript/">Go to "Using TypeScript"</Link>
    </p>
  </Layout>
)

export default IndexPage

There is no need to create a route for the page. Each page component is automatically assigned a route. For example, the page at src/pages/using-typescript.tsx is automatically available at using-typescript.¹ This approach has multiple advantages. First, if you have many pages, you don’t need to manage the routes for them manually. Second, it means that Gatsby can deliver much more rapidly. To see why, let’s look at how to generate a production build for a Gatsby application.

If you stop the Gatsby development server,² you can generate a production build with the following:

$ npm run build

This command runs a gatsby build command, which creates a public directory. And it is the public directory that contains the real magic of Gatsby. For each page, you find two files. First, a generated JavaScript file:

1389 06:48 component---src-pages-using-typescript-tsx-93b78cfadc08d7d203c6.js

Here you can see that the code for using-typescript.tsx is just 1,389 bytes long, which, with the core framework, is just enough JavaScript to build the page. It is not the kind of include-everything script that you find in a create-react-app project.

Second, there is a subdirectory for each page containing a generated HTML file. For using-typescript.tsx, the file is called public/using-typescript/index.html, containing a statically generated version of the web page. It contains the HTML that the using-typescript.tsx component would otherwise render dynamically. At the end of the web page, it loads the JavaScript version of the page to generate any dynamic content.

This file structure means that Gatsby pages load as quickly as static pages. Using the bundled react-helmet library, you can also generate <meta/> header tags with additional features about your site. Both features are great for search engine optimization (SEO).

Discussion

How will the content get into your Gatsby application? You might use a headless content management system, a GraphQL service, a static data source, or something else. Fortunately, Gatsby has many plugins that allow you to connect data sources to your application and then transform the content from other formats, such as Markdown, into HTML.

You can find a complete set of plugins on the Gatsby website.

Most of the time, you choose the plugins you need when you first create the project. To give you a head start, Gatsby also supports start templates. The template provides the initial application structure and configuration. The app we built earlier uses the default starter template, which is quite simple. The gatsby-config.js file in the root of the application configures which plugins your application uses.

But there are masses of Gatsby starters available, preconfigured to build applications that connect to various data sources, with preconfigured options for SEO, styling, offline caching, progressive web applications (PWAs), and more. Whatever kind of content-rich application you are building, there is a starter close to what you need.

There is more information on the Gatsby website about Gatsby starters, as well as a cheat sheet for the most useful tools and commands.

You can download the source for this recipe from the GitHub site.

Problem

Sometimes when you start to build an application, it is not always clear what the significant architectural decisions will be. Should you create an SPA? If performance is critical, should you use server side r? You will need to decide what your deployment platform will be and whether you will write your code in JavaScript or TypeScript.

Many tools require that you answer these questions early on. If you later change your mind, modifying how you build and deploy your application can be complicated.

Solution

If you want to defer decisions about how you build and deploy your application, you should consider using Razzle.

Razzle is a tool for building Universal applications: applications that can execute their JavaScript on the server. Or the client. Or both.

Razzle uses a plugin architecture that allows you to change your mind about how you build your application. It will even let you change your mind about building your code in React, Preact, or some other framework entirely, like Elm or Vue.

You can create a Razzle application with the create-razzle-app command:³

$ npx create-razzle-app my-app

This command creates a new Razzle project in the my-app subdirectory. You can start the development server with the start script:

$ cd my-app
$ npm run start

The start script will dynamically build both client code and server code and then run the server on port 3000, as shown in Figure 1-5.

Figure 1-5. The Razzle front page at http://localhost:3000

When you want to deploy a production version of your application, you can then run the build script:

$ npm run build

Unlike create-react-app, this will build not just the client code but also a Node server. Razzle generates the code in the build subdirectory. The server code will continue to generate static code for your client at runtime. You can start a production server by running the build/server.js file using the start:prod script:

$ npm run start:prod

You can deploy the production server anywhere that Node is available.

The server and the client can both run the same code, which makes it Universal. But how does it do this?

The client and the server have different entry points. The server runs the code in src/server.js; the browser runs the code in src/client.js. Both server.js and client.js then render the same app using src/App.js.

If you want to run your app as an SPA, remove the src/index.js and src/server.js files. Then create an index.html file in the public folder containing a <div/> with an ID of root, and rebuild the application with this:

$ node_modules/.bin/razzle build --type=spa

You will generate a full SPA in build/public/ that you can deploy on any web server.

Discussion

Razzle is so adaptable because it is built from a set of highly configurable plugins. Each plugin is a higher-order function that receives a Webpack configuration and returns a modified version. One plugin might transpile TypeScript code; another might bundle the React libraries.

If you want to switch your application to Vue, you only need to replace the plugins you use.

You can find a list of available plugins on the Razzle website.

You can download the source for this recipe from the GitHub site.

Problem

React generates client code—even if it generates the client code on the server. Sometimes, however, you might have a relatively small amount of application programming interface (API) code that you would prefer to manage as part of the same React application.

Solution

Next.js is a tool for generating React applications and server code. The API end-points and the client pages use default routing conventions, making them simpler to build and deploy than they would be if you manage them yourself. You can find full details about Next.js on the website.

You can create a Next.js application with this command:

$ npx create-next-app my-app

This will use yarn as the package manager if you have it installed. You can force it to use the npm package manager with the --user-npm flag:

$ npx create-next-app --use-npm my-app

This will create a Next.js application in the my-app subdirectory. To start the app, run the dev script (see Figure 1-6):

$ cd my-app
$ npm run dev

Figure 1-6. A Next.js page running at http://localhost:3000

Next.js allows you to create pages without the need to manage any routing configuration. If you add a component script to the pages folder, it will instantly become available through the server. For example, the pages/index.js component generates the home page of the default application.

This approach is similar to the one taken by Gatsby,⁴ but is taken further in Next.js to include server-side code.

Next.js applications usually include some API server code, which is unusual for React applications, which are often built separately from server code. But if you look inside pages/api, you will find an example server endpoint called hello.js:

// Next.js API route support: https://nextjs.org/docs/api-routes/introduction

export default (req, res) => {
  res.status(200).json({ name: 'John Doe' })
}

The routing that mounts this to the endpoint api/hello happens automatically.

Next.js transpiles your code into a hidden directory called .next, which it can then deploy to a service such as Next.js’s own Vercel platform.

If you want, you generate a static build of your application with:

$ node_modules/.bin/next export

The export command will build your client code in a directory called out. The command will convert each page into a statically rendered HTML file, which will load quickly in the browser. At the end of the page, it will load the JavaScript version to generate any dynamic content.

Next.js comes with a bunch of data-fetching options, which allow you to get data from static content, or via headless content management system (CMS) sources.

Discussion

Next.js is in many ways similar to Gatsby. Its focus is on the speed of delivery, with a small amount of configuration. It’s probably most beneficial for teams that will have very little server code.

You can download the source for this recipe from the GitHub site.

Problem

React applications can be large. It’s pretty easy to create a simple React application that is transpiled into bundles of JavaScript code that are several hundred kilobytes in size. You might want to build an app with React-like features but with a much smaller footprint.

Solution

If you want React features but don’t want to pay the price of a React-size JavaScript bundle, consider using Preact.

Preact is not React. It is a separate library, designed to be as close to React as possible but much smaller.

The reason that the React framework is so big is because of the way it works. React components don’t generate elements in the Document Object Model (DOM) of the browser directly. Instead, they build elements within a virtual DOM and then update the actual DOM at frequent intervals. Doing so allows basic DOM rendering to be fast because the actual DOM needs to be updated only when there are actual changes. However, it does have a downside. React’s virtual DOM requires a lot of code to keep it up-to-date. It needs to manage an entire synthetic event model, which parallels the one in the browser. For this reason, the React framework is large and can take some time to download.

One way around this is to use techniques such as SSR, but SSR can be complex to configure.⁵ Sometimes, you want to download a small amount of code. And that’s why Preact exists.

The Preact library, although similar to React, is tiny. At the time of writing, the main Preact library is around 4KB, which is small enough that it’s possible to add React-like features to web pages in barely more code than is required to write native JavaScript.

Preact lets you choose how to use it: as a small JavaScript library included in a web page (the no-tools approach) or as a full-blown JavaScript application.

The no-tools approach is basic. The core Preact library does not support JSX, and you will have no Babel support, so you will not be able to use modern JavaScript. Here is an example web page using the raw Preact library:

<html>
    <head>
        <title>No Tools!</title>
        <script src="https://unpkg.com/preact?umd"></script>
    </head>
    <body>
        <h1>No Tools Preact App!</h1>
        <div id="root"></div>
        <script>
         var h = window.preact.h;
         var render = window.preact.render;

         var mount = document.getElementById('root');

         render(
             h('button',
               {
                   onClick: function() {
                       render(h('div', null, 'Hello'), mount);
                   }
               },
               'Click!'),
             mount
         );
        </script>
    </body>
</html>

This application will mount itself at the <div/> with an ID of root, where it will display a button. When you click the button, it will replace the contents of the root div with the string "Hello", which is about as basic as a Preact app can be.

You would rarely write an application in this way. In reality, you would create a simple build-chain that would, at the least, support modern JavaScript.

Preact supports the entire spectrum of JavaScript applications. At the other extreme, you can create a complete Preact application with preact-cli.

preact-cli is a tool for creating Preact projects and is analogous to tools like create-react-app. You can create a Preact application with:

$ npx preact-cli create default my-app

This command will create your new Preact application in the my-app subdirectory. To start it, run the dev script:

$ cd my-app
$ npm run dev

The server will run on port 8080, as shown in Figure 1-7.

Figure 1-7. A page from Preact

The server generates a web page, which calls back for a JavaScript bundle made from the code in src/index.js.

You now have a full-scale React-like application. The code inside the Home component (src/routes/home/index.js), for example, looks very React-like, with full JSX support:

import { h } from 'preact';
import style from './style.css';

const Home = () => (
    <div class={style.home}>
        <h1>Home</h1>
        <p>This is the Home component.</p>
    </div>
);

export default Home;

The only significant difference from a standard React component is that a function called h is imported from the preact library, instead of importing React from the react library.

However, the size of the application has increased: it is now a little over 300KB. That’s pretty large, but we are still in dev mode. To see the real power of Preact, stop the dev server by pressing Ctrl-C, and then run the build script:

$ npm run build

This command will generate a static version of the application in the build directory. First, this will have the advantage of creating a static copy of the front page, which will render quickly. Second, it will remove all unused code from the application and shrink everything down. If you serve this built version of the app on a standard web server, the browser will transfer only about 50–60KB when it’s opened.

Discussion

Preact is a remarkable project. Despite working in a very different way from React, it provides virtually the same power at a fraction of the size. And the fact that you can use it for anything from the lowliest inline code to a full-blown SPA means it is well worth considering if code size is critical to your project.

You can find out more about Preact on the Preact website.

You can download the source for the no-tools example and the larger Preact example from the GitHub site.

If you would like to make Preact look even more like React, see the preact-compat library.

Finally, for a project that takes a similar approach to Preact, look at InfernoJS.

Problem

Large organizations often develop several React applications at the same time. If you’re a consultancy, you might create applications for multiple organizations. If you’re a software house, you might create various applications that require the same look and feel, so you will probably want to build shared components to use across several applications.

When you create a component project, you need to create a directory structure, select a set of tools, choose a set of language features, and create a build chain that can bundle your component in a deployable format. This process can be just as tedious as manually creating a project for an entire React application.

Solution

You can use the nwb toolkit to create complete React applications or single React components. It can also create components for use within Preact and InfernoJS projects, but we concentrate on React components here.

To create a new React component project, you will first need to install the nwb tool globally:

$ npm install -g nwb

You can then create a new project with the nwb command:

$ nwb new react-component my-component

When you run this command, it will ask you several questions about the type of library you want to build. For example, it will ask you if you’re going to build ECMAScript modules:

Creating a react-component project...
? Do you want to create an ES modules build? (Y/n)

This option allows you to build a version including an export statement, which Webpack can use to decide if it needs to include the component in a client application. You will also be asked if you want to create a Universal Module Definition (UMD):

? Do you want to create a UMD build? (y/N)

That’s useful if you want to include your component in a <script/> within a web page. For our example, we won’t create a UMD build.

After the questions, the tool will create an nwb component project inside the my-component subdirectory. The project comes with a simple wrapper application that you can start with the start script:

$ cd my-component
$ npm run start

The demo application runs on port 3000, as shown in Figure 1-8.

Figure 1-8. An nwb component

The application will contain a single component defined in src/index.js:

import React, { Component } from 'react'

export default class extends Component {
  render() {
    return (
      <div>
        <h2>Welcome to React components</h2>
      </div>
    )
  }
}

You can now build the component as you would any React project. When you are ready to create a publishable version, type:

$ npm run build

The built component will be in lib/index.js, which you can deploy to a repository for use within other projects.

Discussion

For further details on creating nwb components, see the nwb guide to developing components and libraries.

You can download the source for this recipe from the GitHub site.

Problem

The Rails framework was created before interactive JavaScript applications became popular. Rails applications follow a more traditional model for web application development, in which it generates HTML pages on the server in response to browser requests. But sometimes, you may want to include more interactive elements inside a Rails application.

Solution

You can use the Webpacker library to insert React applications into Rails-generated web pages. To see how it works, let’s first generate a Rails application that includes Webpacker:

$ rails new my-app --webpack=react

This command will create a Rails application in a directory called my-app that is preconfigured to run a Webpacker server. Before we start the application, let’s go into it and generate an example page/controller:

$ cd my-app
$ rails generate controller Example index

That code will generate this template page at app/views/example/index.html.erb:

<h1>Example#index</h1>
<p>Find me in app/views/example/index.html.erb</p>

Next, we need to create a small React application that we can insert into this page. Rails inserts Webpacker applications as packs: small JavaScript bundles within Rails. We’ll create a new pack in app/javascript/packs/counter.js containing a simple counter component:

import React, { useState } from 'react'
import ReactDOM from 'react-dom'

const Counter = (props) => {
  const [count, setCount] = useState(0)
  return (
    <div className="Counter">
      You have clicked the button {count} times.
      <button onClick={() => setCount((c) => c + 1)}>Click!</button>
    </div>
  )
}

document.addEventListener('DOMContentLoaded', () => {
  ReactDOM.render(
    <Counter />,
    document.body.appendChild(document.createElement('div'))
  )
})

This application updates a counter every time a user clicks the button.

We can now insert the pack into the web page by adding a single line of code to the template page:

<h1>Example#index</h1>
<p>Find me in app/views/example/index.html.erb</p>
<%= javascript_pack_tag 'counter' %>

Finally, we can run the Rails server on port 3000:

$ rails server

You will see the http://localhost:3000/example/index.html page in Figure 1-9.

Figure 1-9. A React app embedded in http://localhost:3000/example/index.html

Discussion

Behind the scenes, as you have probably guessed, Webpacker transforms the application using a copy of Webpack, which you can configure with the app/config/webpacker.yml config file.

Webpacker is used alongside Rails code rather than as a replacement for it. You should consider using it if your Rails application requires a small amount of additional interactivity.

You can find out more about Webpacker on the Webpacker GitHub site.

You can download the source for this recipe from the GitHub site.

Problem

There are sometimes circumstances where it is challenging to add React code into existing content. For example, in some CMS configurations, users are not allowed to insert additional JavaScript into the body of a page. In these cases, it would be helpful to have some standardized way to insert JavaScript applications safely into a page.

Solution

Custom elements are a standard way of creating new HTML elements you can use on a web page. In effect, they extend the HTML language by making more tags available to a user.

This recipe looks at how we can use a lightweight framework like Preact to create custom elements, which we can publish on a third-party server.

Let’s begin by creating a new Preact application. This application will serve the custom element that we will be able to use elsewhere:⁶

$ preact create default my-element

Now we will change into the app’s directory and add the preact-custom-element library to the project:

$ cd my-element
$ npm install preact-custom-element

The preact-custom-element library will allow us to register a new custom HTML element in a browser.

Next, we need to modify the src/index.js file of the Preact project so that it registers a new custom element, which we will call components/Converter/index.js:

import register from 'preact-custom-element'
import Converter from './components/Converter'

register(Converter, 'x-converter', ['currency'])

The register method tells the browser that we want to create a new custom HTML element called <x-converter/> that has a single property called currency, which we will define in src/components/Converter/index.js:

import { h } from 'preact'
import { useEffect, useState } from 'preact/hooks'
import 'style/index.css'

const rates = { gbp: 0.81, eur: 0.92, jpy: 106.64 }

export default ({ currency = 'gbp' }) => {
  const [curr, setCurr] = useState(currency)
  const [amount, setAmount] = useState(0)

  useEffect(() => {
    setCurr(currency)
  }, [currency])

  return (
    <div className="Converter">
      <p>
        <label htmlFor="currency">Currency: </label>
        <select
          name="currency"
          value={curr}
          onChange={(evt) => setCurr(evt.target.value)}
        >
          {Object.keys(rates).map((r) => (
            <option value={r}>{r}</option>
          ))}
        </select>
      </p>
      <p className="Converter-amount">
        <label htmlFor="amount">Amount: </label>
        <input
          name="amount"
          size={8}
          type="number"
          value={amount}
          onInput={(evt) => setAmount(parseFloat(evt.target.value))}
        />
      </p>
      <p>
        Cost:
        {((amount || 0) / rates[curr]).toLocaleString('en-US', {
          style: 'currency',
          currency: 'USD',
        })}
      </p>
    </div>
  )
}

Our Converter component is a currency converter, which in our example uses a fixed set of exchange rates. If we now start our Preact server:

$ npm run dev

the JavaScript for the custom element will be available at http://localhost:8080/bundle.js.

To use this new custom element, let’s create a static web page somewhere with this HTML:

<html>
    <head>
        <script src="https://unpkg.com/babel-polyfill/dist/polyfill.min.js">
        </script>
        <script src="https://unpkg.com/@webcomponents/webcomponentsjs">
        </script>
        <!-- Replace this with the address of your custom element -->
        <script type="text/javascript" src="http://localhost:8080/bundle.js">
        </script>
    </head>
    <body>
        <h1>Custom Web Element</h1>
        <div style="float: right; clear: both">
            <!-- This tag will insert the Preact app -->
            <x-converter currency="jpy"/>
        </div>
        <p>This page contains an example custom element called
            <code>&lt;x-converter/&gt;</code>,
            which is being served from a different location</p>
    </body>
</html>

This web page includes the definition of the custom element in the final <script/> of the <head/> element. To ensure that the custom element is available across both new and old browsers, we also include a couple of shims from unpkg.com.

Now that we’ve included the custom element code in the web page, we can insert <x-converter/> tags into the code, as if they are part of standard HTML. In our example, we are also passing a currency property to the underlying Preact component.

We can run this page through a web server, separate from the Preact server. Figure 1-10 shows the new custom element.

Figure 1-10. The custom element embedded in a static page

Discussion

The custom element does not need to be on the same server as the web page that uses it, which means that we can use custom elements to publish widgets for any web page. Because of this, you might want to check the Referer header on any incoming request to the component to prevent any unauthorized usage.

Our example is serving the custom element from Preact’s development server. For a production release, you would probably want to create a static build of the component, which will likely be significantly smaller.⁸

You can download the source for this recipe from the GitHub site.

Problem

React components are the stable building material of React applications. If we write them carefully, we can reuse the components in other React applications. But when you build a component, it takes work to check how it works in all circumstances. For example, in an asynchronous application, React might render the component with undefined properties. Will the component still render correctly? Will it show errors?

But if you are building components as part of a complex application, it can be tough to create all of the situations with which your component will need to cope.

Also, if you have specialized user experience (UX) developers working on your team, it can waste a lot of time if they have to navigate through an application to view the single component they have in development.

It would be helpful if there were some way of displaying a component in isolation and passing it example sets of properties.

Solution

Storybook is a tool for displaying libraries of components in various states. You could describe it as a gallery for components, but that’s probably selling it short. In reality, Storybook is a tool for component development.

How do we add Storybook to a project? Let’s begin by creating a React application with create-react-app:

$ npx create-react-app my-app
$ cd my-app

Now we can add Storybook to the project:

$ npx sb init

We then start the Storybook server with yarn or npm:

$ npm run storybook

Storybook runs a separate server on port 9000, as you can see in Figure 1-11. When you use Storybook, there is no need to run the actual React application.

Figure 1-11. The welcome page in Storybook

Storybook calls a single component rendered with example properties a story. The default installation of Storybook generates sample stories in the src/stories directory of the application. For example, this is src/stories/Button.stories.js:

import React from 'react';

import { Button } from './Button';

export default {
  title: 'Example/Button',
  component: Button,
  argTypes: {
    backgroundColor: { control: 'color' },
  },
};

const Template = (args) => <Button {...args} />;

export const Primary = Template.bind({});
Primary.args = {
  primary: true,
  label: 'Button',
};

export const Secondary = Template.bind({});
Secondary.args = {
  label: 'Button',
};

export const Large = Template.bind({});
Large.args = {
  size: 'large',
  label: 'Button',
};

export const Small = Template.bind({});
Small.args = {
  size: 'small',
  label: 'Button',
};

Storybook watches for files named *.stories.js in your source folder, and it doesn’t care where they are, so you are free to create them where you like. One typical pattern places the stories in a folder alongside the component they are showcasing. So if you copy the folder to a different application, you can include stories as living documentation.

Figure 1-12 shows what Button.stories.js looks like in Storybook.

Figure 1-12. An example story

Discussion

Despite its simple appearance, Storybook is a productive development tool. It allows you to focus on one component at a time. Like a kind of visual unit test, it enables you to try a component in a series of possible scenarios to check that it behaves appropriately.

Storybook also has a large selection of additional add-ons.

The add-ons allow you to:

• Check for accessibility problems (addon-a11y)

• Add interactive controls for setting properties (Knobs)

• Include inline documentation for each story (Docs)

• Record snapshots of the HTML to test the impact of changes (Storyshots)

And do much more.

For further information about Storybook, see the website.

You can download the source for this recipe from the GitHub site.

Problem

Most React projects include a testing library. The most common is probably @testing-library/react, which comes bundled with create-react-app, or Enzyme, which is used by Preact.

But nothing quite beats testing code in a real browser, with all the additional complications that entails. Traditionally, browser testing can be unstable and requires frequent maintenance as you need to upgrade browser drivers (such as ChromeDriver) every time you upgrade the browser.

Add to that the issue of generating test data on a backend server, and browser-based testing can be complex to set up and manage.

Solution

The Cypress testing framework avoids many of the downsides of traditional browser testing. It runs in a browser but avoids the need for an external web-driver tool. Instead, it communicates directly with a browser, like Chrome or Electron, over a network port and then injects JavaScript to run much of the test code.

Let’s create an application create-react-app to see how it works:

$ npx create-react-app --use-npm my-app

Now let’s go into the app directory and install Cypress:

$ cd my-app
$ npm install cypress --save-dev

Before we run Cypress, we need to configure it so that it knows how to find our application. We can do this by creating a cypress.json file in the application directory and telling it the uniform resource locator (URL) of our app:

{
  "baseUrl": "http://localhost:3000/"
}

Once we have started the main application:

$ npm start

we can then open Cypress:

$ npx cypress open

The first time you run Cypress, it will install all the dependencies it needs. We’ll now create a test in the cypress/integration directory called screenshot.js, which opens the home page and takes a screenshot:

describe('screenshot', () => {
    it('should be able to take a screenshot', () => {
        cy.visit('/');
        cy.screenshot('frontpage');
    });
});

You’ll notice that we wrote the tests in Jest format. Once you save the test, it will appear in the main Cypress window, shown in Figure 1-13.

Figure 1-13. The Cypress window

If you double-click the test, Cypress will run it in a browser. The front page of the application will open, and the test will save a screenshot to cypress/screenshots/screenshot.js/frontpage.png.

Discussion

Here are some example commands you can perform with Cypress:

These are just some of the commands that interact with the web page. But Cypress has another trick up its sleeve. Cypress can also modify the code inside the browser to change the time (cy.clock()), the cookies (cy.setCookie()), the local storage (cy.clearLocalStorage()) and—most impressively—fake requests and responses to an API server.

It does this by modifying the networking functions that are built into the browser so that this code:

cy.route("/api/server?*", [{some: 'Data'}])

will intercept any requests to a server endpoint beginning /api/server? and return the JSON array [{some: 'Data'}].

Simulating network responses can completely change the way teams develop applications because it decouples the frontend development from the backend. The browser tests can specify what data they need without having to create a real server and database.

To learn more about Cypress, visit the documentation site.

You can download the source for this recipe from the GitHub site.

Problem

People use most applications on both mobile and laptop computers, which means you probably want your React application to work well across all screen sizes. Making your application responsive involves relatively simple CSS changes to adjust the sizing of text and screen layout, and more substantial changes, which can give mobile and desktop users very different experiences when navigating around your site.

Our example application shows the names and addresses of a list of people. In Figure 2-1, you can see the application running on a desktop machine.

Figure 2-1. The desktop view of the app

But this layout won’t work very well on a mobile device, which might have space to display either the list of people or the details of one person, but not both.

What can we do in React to provide a custom navigation experience for both mobile and desktop users without creating two completely separate versions of the application?

Solution

We’re going to use responsive routes. A responsive route changes according to the size of the user’s display. Our existing application uses a single route for displaying the information for a person: /people/:id.

When you navigate to this route, the browser shows the page in Figure 2-1. You can see the people listed down the left side. The page highlights the selected person and displays their details on the right.

We’re going to modify our application to cope with an additional route at /people. Then we will make the routes responsive so that the user will see different things on different devices:

What ingredients will we need to do this? First, we need to install react-router-dom if our application does not already have it:

$ npm install react-router-dom

The react-router-dom library allows us to coordinate the browser’s current location with the state of our application. Next, we will install the react-media library, which allows us to create React components that respond to changes in the display screen size:

$ npm install react-media

Now we’re going to create a responsive PeopleContainer component that will manage the routes we want to create. On small screens, our component will display either a list of people or the details of a single person. On large screens, it will show a combined view of a list of people on the left and the details of a single person on the right.

The PeopleContainer will use the Media component from react-media. The Media component performs a similar job to the CSS @media rule: it allows you to generate output for a specified range of screen sizes. The Media component accepts a queries property that allows you to specify a set of screen sizes. We’re going to define a single screen size—small—that we’ll use as the break between mobile and desktop screens:

<Media queries={{
        small: "(max-width: 700px)"
    }}>
  ...
</Media>

The Media component takes a single child component, which it expects to be a function. This function is given a size object that can be used to tell what the current screen size is. In our example, the size object will have a small attribute, which we can use to decide what other components to display:

<Media queries={{
        small: "(max-width: 700px)"
    }}>
  {
    size => size.small ? [SMALL SCREEN COMPONENTS] : [BIG SCREEN COMPONENTS]
  }
</Media>

Before we look at the details of what code we are going to return for large and small screens, it’s worth taking a look at how we will mount the PeopleContainer in our application. The following code is going to be our main App component:

import { BrowserRouter, Link, Route, Switch } from 'react-router-dom'
import PeopleContainer from './PeopleContainer'

function App() {
  return (
    <BrowserRouter>
      <Switch>
        <Route path="/people">
          <PeopleContainer />
        </Route>
        <Link to="/people">People</Link>
      </Switch>
    </BrowserRouter>
  )
}

export default App

We are using the BrowserRouter from react-router-dom, which links our code and the HTML5 history API in the browser. We need to wrap all of our routes in a Router to give them access to the browser’s current address.

Inside the BrowserRouter, we have a Switch. The Switch looks at the components inside it, looking for a Route that matches the current location. Here we have a single Route matching paths that begin with /people. If that’s true, we display the People​Con⁠tainer. If no route matches, we fall through to the end of the Switch and render a Link to the /people path. So when someone goes to the front page of the application, they see only a link to the People page.

So we know if we’re in the PeopleContainer, we’re already on a route that begins with /people/…. If we’re on a small screen, we need to either show a list of people or display the details of a single person, but not both. We can do this with Switch:

<Media queries={{
        small: "(max-width: 700px)"
    }}>
  {
    size => size.small ? [SMALL SCREEN COMPONENTS]
        <Switch>
          <Route path='/people/:id'>
            <Person/>
          </Route>
          <PeopleList/>
        </Switch>
        : [BIG SCREEN COMPONENTS]
  }
</Media>

On a small device, the Media component will call its child function with a value that means size.small is true. Our code will render a Switch that will show a Person component if the current path contains an id. Otherwise, the Switch will fail to match that Route and will instead render a PeopleList.

Ignoring the fact that we’ve yet to write the code for large screens, if we were to run this code right now on a mobile device and hit the People link on the front page, we would navigate to people, which could cause the application to render the PeopleList component. The PeopleList component displays a set of links to people with paths of the form /people/id.¹ When someone selects a person from the list, our components are re-rendered, and this time PeopleContainer displays the details of a single person (see Figure 2-2).

Figure 2-2. In mobile view: the list of people (left) that links to a person’s details (right)

So far, so good. Now we need to make sure that our application still works for larger screens. We need to generate responsive routes in PeopleContainer for when size.small is false. If the current route is of the form /people/id, we can display the PeopleList component on the left and the Person component on the right:

<div style={{display: 'flex'}}>
  <PeopleList/>
  <Person/>
</div>

Unfortunately, that doesn’t handle the case where the current path is /people. We need another Switch that either will display the details for a single person or will redirect to /people/first-person-id for the first person in the list of people.

<div style={{display: 'flex'}}>
    <PeopleList/>
    <Switch>
        <Route path='/people/:id'>
            <Person/>
        </Route>
        <Redirect to={`/people/${people[0].id}`}/>
    </Switch>
</div>

The Redirect component doesn’t perform an actual browser redirect. It simply updates the current path to /people/first-person-id, which causes the PeopleContainer to re-render. It’s similar to making a call to history.push() in JavaScript, except it doesn’t add an extra page to the browser history. If a person navigates to /people, the browser will simply change its location to /people/first-person-id.

If we were now to go to /people on a laptop or larger tablet, we would see the list of people next to the details for the first person (Figure 2-3).

Figure 2-3. What you see at http://localhost:3000/people on a large display

Here is the final version of our PeopleContainer:

import Media from 'react-media'
import { Redirect, Route, Switch } from 'react-router-dom'
import Person from './Person'
import PeopleList from './PeopleList'
import people from './people'

const PeopleContainer = () => {
  return (
    <Media
      queries={{
        small: '(max-width: 700px)',
      }}
    >
      {(size) =>
        size.small ? (
          <Switch>
            <Route path="/people/:id">
              <Person />
            </Route>
            <PeopleList />
          </Switch>
        ) : (
          <div style={{ display: 'flex' }}>
            <PeopleList />
            <Switch>
              <Route path="/people/:id">
                <Person />
              </Route>
              <Redirect to={`/people/${people[0].id}`} />
            </Switch>
          </div>
        )
      }
    </Media>
  )
}

export default PeopleContainer

Discussion

Declarative routing inside components can seem an odd thing when you first meet it. Suppose you’ve used a centralized routing model before. In that case, declarative routes may at first seem messy because they spread the wiring of your application across several components rather than in a single file. Instead of creating clean components that know nothing of the outside world, you are suddenly giving the intimate knowledge of the paths used in the application, which might make them less portable.

However, responsive routes show the real power of declarative routing. If you’re concerned about your components knowing too much about the paths in your application, consider extracting the path strings into a shared file. That way, you will have the best of both worlds: components that modify their behavior based upon the current path and a centralized set of path configurations.

You can download the source for this recipe from the GitHub site.

Problem

It is often helpful to manage the internal state of a component using the route that displays it. For example, this is a React component that displays two tabs of information: one for /people and one for /offices:

import { useState } from 'react'
import People from './People'
import Offices from './Offices'

import './About.css'

const OldAbout = () => {
  const [tabId, setTabId] = useState('people')

  return (
    <div className="About">
      <div className="About-tabs">
        <div
          onClick={() => setTabId('people')}
          className={
            tabId === 'people' ? 'About-tab active' : 'About-tab'
          }
        >
          People
        </div>
        <div
          onClick={() => setTabId('offices')}
          className={
            tabId === 'offices' ? 'About-tab active' : 'About-tab'
          }
        >
          Offices
        </div>
      </div>
      {tabId === 'people' && <People />}
      {tabId === 'offices' && <Offices />}
    </div>
  )
}

export default OldAbout

When a user clicks a tab, an internal tabId variable is updated, and the People or Offices component is displayed (see Figure 2-4).

Figure 2-4. By default, the OldAbout component shows people’s details

What’s the problem? The component works, but if we select the Offices tab and then refresh the page, the component resets to the People tab. Likewise, we can’t bookmark the page when it’s on the Offices tab. We can’t create a link anywhere else in the application, which takes us directly to Offices. Accessibility hardware is less likely to notice that the tabs are working as hyperlinks because they are not rendered in that way.

Solution

We are going to move the tabId state from the component into the current browser location. So instead of rendering the component at /about and then using onClick events to change the internal state, we are instead going to have routes to /about/people and /about/offices, which display one tab or the other. The tab selection will survive a browser refresh. We can bookmark the page on a given tab or create a link to a given tab. And we make the tabs actual hyperlinks, which will be recognized as such by anyone navigating with a keyboard or screen reader.

What ingredients do we need? Just one: react-router-dom:

$ npm install react-router-dom

react-router-dom will allow us to synchronize the current browser URL with the components that we render on the screen.

Our existing application is already using react-router-dom to display the OldAbout component at path /oldabout as you can see from this fragment of code from the App.js file:

<Switch>
    <Route path="/oldabout">
        <OldAbout/>
    </Route>
    <p>Choose an option</p>
</Switch>

You can see the complete code for this file at the GitHub repository.

We’re going to create a new version of the OldAbout component called About, and we’re going to mount it at its own route:

<Switch>
    <Route path="/oldabout">
        <OldAbout/>
    </Route>
    <Route path="/about/:tabId?">
        <About/>
    </Route>
    <p>Choose an option</p>
</Switch>

This addition allows us to open both versions of the code in the example application.

Our new version is going to appear to be virtually identical to the old component. We’ll extract the tabId from the component and move it into the current path.

Setting the path of the Route to /about/:tabId? means that /about, /about/offices, and /about/people will all mount our component. The ? indicates that the tabId parameter is optional.

We’ve now done the first part: we’ve put the component’s state into the path that displays it. We now need to update the component to interact with the route rather than an internal state variable.

In the OldAbout component, we had onClick listeners on each of the tabs:

<div onClick={() => setTabId("people")}
     className={tabId === "people" ? "About-tab active" : "About-tab"}
>
    People
</div>
<div onClick={() => setTabId("offices")}
     className={tabId === "offices" ? "About-tab active" : "About-tab"}
>
    Offices
</div>

We’re going to convert these into Link components, going to /about/people and /about/offices. In fact, we’re going to convert them into NavLink components. A NavLink is like a link, except it has the ability to set an additional class name, if the place it’s linking to is the current location. This means we don’t need the className logic in the original code:

<NavLink to="/about/people"
         className="About-tab"
         activeClassName="active">
    People
</NavLink>
<NavLink to="/about/offices"
         className="About-tab"
         activeClassName="active">
    Offices
</NavLink>

We no longer set the value of a tabId variable. We instead go to a new location with a new tabId value in the path.

But what do we do to read the tabId value? The OldAbout code displays the current tab contents like this:

{tabId === "people" && <People/>}
{tabId === "offices" && <Offices/>}

This code can be replaced with a Switch and a couple of Route components:

<Switch>
    <Route path='/about/people'>
        <People/>
    </Route>
    <Route path='/about/offices'>
        <Offices/>
    </Route>
</Switch>

We’re now almost finished. There’s just one step remaining: deciding what to do if the path is /about and contains no tabId.

The OldAbout sets a default value for tabId when it first creates the state:

const [tabId, setTabId] = useState("people")

We can achieve the same effect by adding a Redirect to the end of our Switch. The Switch will process its child components in order until it finds a matching Route. If no Route matches the current path, it will reach the Redirect, which will change the address to /about/people. This will cause a re-render of the About component, and the People tab will be selected by default:

<Switch>
    <Route path='/about/people'>
        <People/>
    </Route>
    <Route path='/about/offices'>
        <Offices/>
    </Route>
    <Redirect to='/about/people'/>
</Switch>

This is our completed About component:

import { NavLink, Redirect, Route, Switch } from 'react-router-dom'
import './About.css'
import People from './People'
import Offices from './Offices'

const About = () => (
  <div className="About">
    <div className="About-tabs">
      <NavLink
        to="/about/people"
        className="About-tab"
        activeClassName="active"
      >
        People
      </NavLink>
      <NavLink
        to="/about/offices"
        className="About-tab"
        activeClassName="active"
      >
        Offices
      </NavLink>
    </div>
    <Switch>
      <Route path="/about/people">
        <People />
      </Route>
      <Route path="/about/offices">
        <Offices />
      </Route>
      <Redirect to="/about/people" />
    </Switch>
  </div>
)

export default About

We no longer need an internal tabId variable, and we now have a purely declarative component (see Figure 2-5).

Figure 2-5. Going to http://localhost/about/offices with the new component

Discussion

Moving state out of your components and into the address bar can simplify your code, but this is merely a fortunate side effect. The real value is that your application starts to behave less like an application and more like a website. We can bookmark pages, and the browser’s Back and Forward buttons work correctly. Managing more state in routes is not an abstract design decision; it’s a way of making your application less surprising to users.

You can download the source for this recipe from the GitHub site.

Problem

We use routes in React applications so that we make more of the facilities of the browser. We can bookmark pages, create deep links into an app, and go backward and forward in history.

However, once we use routes, we make the component dependent upon something outside itself: the browser location. That might not seem like too big an issue, but it does have consequences.

Let’s say we want to unit test a route-aware component. As an example, let’s create a unit test for the About component we built in Recipe 2.2:²

describe('About component', () => {
  it('should show people', () => {
    render(<About />)
    expect(screen.getByText('Kip Russel')).toBeInTheDocument()
  })
})

This unit test renders the component and then checks that it can find the name “Kip Russel” appearing in the output. When we run this test, we get the following error:

console.error node_modules/jsdom/lib/jsdom/virtual-console.js:29
    Error: Uncaught [Error: Invariant failed: You should not use <NavLink>
        outside a <Router>]

The error occurred because a NavLink could not find a Router higher in the component tree. That means we need to wrap the component in a Router before we test it.

Also, we might want to write a unit test that checks that the About component works when we mount it on a specific route. Even if we provide a Router component, how will we fake a particular route?

It’s not just an issue with unit tests. If we’re using a library tool like Storybook,³ we might want to show an example of how a component appears when we mount it on a given path.

We need something like an actual browser router but that allows us to specify its behavior.

Solution

The react-router-dom library provides just such a router: MemoryRouter. The MemoryRouter appears to the outside world just like BrowserRouter. The difference is that while the BrowserRouter is an interface to the underlying browser history API, the MemoryRouter has no such dependency. It can keep track of the current location, and it can go backward and forward in history, but it achieves this through simple memory structures.

Let’s take another look at that failing unit test. Instead of just rendering the About component, let’s wrap it in a MemoryRouter:

describe('About component', () => {
  it('should show people', () => {
    render(
      <MemoryRouter>
        <About />
      </MemoryRouter>
    )

    expect(screen.getByText('Kip Russel')).toBeInTheDocument()
  })
})

Now, when we run the test, it works. That’s because the MemoryRouter injects a mocked-up version of the API into the context. That makes it available to all of its child components. The About component can now render a Link or Route because the history is available.

But the MemoryRouter has an additional advantage. Because it’s faking the browser history API, it can be given a completely fake history, using the initialEntries property. The initialEntries property should be set to an array of history entries. If you pass a single value array, it will be interpreted as the current location. That allows you to write unit tests that check for component behavior when it’s mounted on a given route:

describe('About component', () => {
  it('should show offices if in route', () => {
    render(
      <MemoryRouter initialEntries={[{ pathname: '/about/offices' }]}>
        <About />
      </MemoryRouter>
    )

    expect(screen.getByText('South Dakota')).toBeInTheDocument()
  })
})

We can use a real BrowserRouter inside Storybook because we’re in a real browser, but the MemoryRouter also allows us to fake the current location, as we do in the ToAboutOffices Storybook story (see Figure 2-6).

Figure 2-6. Using MemoryRouter, we can fake the /about/offices route

Discussion

Routers let you separate the details of where you want to go from how you’re going to get there. In this recipe, we see one advantage of this separation: we can create a fake browser location to examine component behavior on different routes. This separation allows you to change the way the application follows links without breaking. If you convert your SPA to an SSR application, you swap your BrowserRouter for a StaticRouter. The links used to make calls into the browser’s history API will become native hyperlinks that cause the browser to make native page loads. Routers are an excellent example of the advantages of splitting policy (what you want to do) from mechanisms (how you’re going to do it).

You can download the source for this recipe from the GitHub site.

Problem

Sometimes you need to ask a user to confirm that they want to leave a page if they’re in the middle of editing something. This seemingly simple task can be complicated because it relies on spotting when the user clicks the Back button and then finding a way to intercept the move back through history and potentially canceling it (see Figure 2-7).

Figure 2-7. Asking for a confirmation before leaving

What if there are several pages in the application that need the same feature? Is there a simple way to create this feature across any component that needs it?

Solution

The react-router-dom library includes a component called Prompt, which asks users to confirm that they want to leave a page.

The only ingredient we need for this recipe is the react-router-dom library itself:

npm install react-router-dom

Let’s say we have a component called Important mounted at /important, which allows a user to edit a piece of text:

import React, { useEffect, useState } from 'react'

const Important = () => {
  const initialValue = 'Initial value'

  const [data, setData] = useState(initialValue)
  const [dirty, setDirty] = useState(false)

  useEffect(() => {
    if (data !== initialValue) {
      setDirty(true)
    }
  }, [data, initialValue])

  return (
    <div className="Important">
      <textarea
        onChange={(evt) => setData(evt.target.value)}
        cols={40}
        rows={12}
      >
        {data}
      </textarea>
      <br />
      <button onClick={() => setDirty(false)} disabled={!dirty}>
        Save
      </button>
    </div>
  )
}

export default Important

Important is already tracking whether the text in the textarea has changed from the original value. If the text is different, the value of dirty is true. How do we ask the user to confirm they want to leave the page if they click the Back button when dirty is true?

We add a Prompt component:

return (
  <div className="Important">
    <textarea
      onChange={(evt) => setData(evt.target.value)}
      cols={40}
      rows={12}
    >
      {data}
    </textarea>
    <br />
    <button onClick={() => setDirty(false)} disabled={!dirty}>
      Save
    </button>
    <Prompt
      when={dirty}
      message={() => 'Do you really want to leave?'}
    />
  </div>
)

If the user edits the text and then hits the Back button, the Prompt appears (see Figure 2-8).

Figure 2-8. The Prompt asks the user to confirm they want to leave

Adding the confirmation is easy, but the default prompt interface is a simple JavaScript dialog. It would be helpful to decide for ourselves how we want the user to confirm they’re leaving.

To demonstrate how we can do this, let’s add the Material-UI component library to the application:

$ npm install '@material-ui/core'

The Material-UI library is a React implementation of Google’s Material Design standard. We’ll use it as an example of how to replace the standard Prompt interface with something more customized.

The Prompt component does not render any UI. Instead, the Prompt component asks the current Router to show the confirmation. By default, BrowserRouter shows the default JavaScript dialog, but you can replace this with your own code.

When the BrowserRouter is added to the component tree, we can pass it a property called getUserConfirmation:

<div className="App">
    <BrowserRouter
        getUserConfirmation={(message, callback) => {
          // Custom code goes here
        }}
    >
        <Switch>
            <Route path='/important'>
                <Important/>
            </Route>
        </Switch>
    </BrowserRouter>
</div>

The getUserConfirmation property is a function that accepts two parameters: the message it should display and a callback function.

When the user clicks the Back button, the Prompt component will run getUser​Con⁠firmation and then wait for the callback function to be called with the value true or false.

The callback function returns the user’s response asynchronously. The Prompt component will wait while we ask the user what they want to do. That allows us to create a custom interface.

Let’s create a custom Material-UI dialog called Alert. We’ll show this instead of the default JavaScript modal:

import Button from '@material-ui/core/Button'
import Dialog from '@material-ui/core/Dialog'
import DialogActions from '@material-ui/core/DialogActions'
import DialogContent from '@material-ui/core/DialogContent'
import DialogContentText from '@material-ui/core/DialogContentText'
import DialogTitle from '@material-ui/core/DialogTitle'

const Alert = ({ open, title, message, onOK, onCancel }) => {
  return (
    <Dialog
      open={open}
      onClose={onCancel}
      aria-labelledby="alert-dialog-title"
      aria-describedby="alert-dialog-description"
    >
      <DialogTitle id="alert-dialog-title">{title}</DialogTitle>
      <DialogContent>
        <DialogContentText id="alert-dialog-description">
          {message}
        </DialogContentText>
      </DialogContent>
      <DialogActions>
        <Button onClick={onCancel} color="primary">
          Cancel
        </Button>
        <Button onClick={onOK} color="primary" autoFocus>
          OK
        </Button>
      </DialogActions>
    </Dialog>
  )
}

export default Alert

Of course, there is no reason why we need to display a dialog. We could show a countdown timer or a snackbar message or automatically save the user’s changes. But we will display a custom Alert dialog.

How will we use the Alert component in our interface? The first thing we’ll need to do is create our own getUserConfirmation function. We’ll store the message and the callback function and then set a Boolean value saying that we want to open the Alert dialog:

const [confirmOpen, setConfirmOpen] = useState(false)
const [confirmMessage, setConfirmMessage] = useState()
const [confirmCallback, setConfirmCallback] = useState()

return (
  <div className="App">
    <BrowserRouter
      getUserConfirmation={(message, callback) => {
        setConfirmMessage(message)
        // Use this setter form because callback is a function
        setConfirmCallback(() => callback)
        setConfirmOpen(true)
      }}
    >
  .....

It’s worth noting that when we store the callback function, we use setConfirmCallback(() => callback) instead of simply writing setConfirmCallback(callback). That’s because the setters returned by the useState hook will execute any function passed to them, rather than store them.

We can then use the values of confirmMessage, confirmCallback, and confirmOpen to render the Alert in the interface.

This is the complete App.js file:

import { useState } from 'react'
import './App.css'
import { BrowserRouter, Link, Route, Switch } from 'react-router-dom'
import Important from './Important'
import Alert from './Alert'

function App() {
  const [confirmOpen, setConfirmOpen] = useState(false)
  const [confirmMessage, setConfirmMessage] = useState()
  const [confirmCallback, setConfirmCallback] = useState()

  return (
    <div className="App">
      <BrowserRouter
        getUserConfirmation={(message, callback) => {
          setConfirmMessage(message)
          // Use this setter form because callback is a function
          setConfirmCallback(() => callback)
          setConfirmOpen(true)
        }}
      >
        <Alert
          open={confirmOpen}
          title="Leave page?"
          message={confirmMessage}
          onOK={() => {
            confirmCallback(true)
            setConfirmOpen(false)
          }}
          onCancel={() => {
            confirmCallback(false)
            setConfirmOpen(false)
          }}
        />
        <Switch>
          <Route path="/important">
            <Important />
          </Route>
          <div>
            <h1>Home page</h1>
            <Link to="/important">Go to important page</Link>
          </div>
        </Switch>
      </BrowserRouter>
    </div>
  )
}

export default App

Now when a user backs out of an edit, they see the custom dialog, as shown in Figure 2-9.

Figure 2-9. The custom Alert appears when the user clicks the Back button

Discussion

In this recipe, we have re-implemented the Prompt modal using a component library, but you don’t need to be limited to just replacing one dialog box with another. There is no reason why, if someone leaves a page, that you couldn’t do something else: such as store the work-in-progress somewhere so that they could return to it later. The asynchronous nature of the getUserConfirmation function allows this flexibility. It’s another example of how react-router-dom abstracts away a cross-cutting concern.

You can download the source for this recipe from the GitHub site.

Problem

Native and desktop applications often use animation to connect different elements visually. If you tap an item in a list, it expands to show you the details. Swiping left or right can be used to indicate whether a user accepts or rejects an option.

Animations, therefore, are often used to indicate a location change. They zoom in on the details. They take you to the next person on the list. We reflect a change in the URL with a matching animation.

But how do we create an animation when we move from one location to another?

Solution

For this recipe, we’re going to need the react-router-dom library and the react-transition-group library:

$ npm install react-router-dom
$ npm install react-transition-group

We’re going to animate the About component that we’ve used previously.⁴ The About component has two tabs called People and Offices, which are displayed for the routes /about/people and /about/offices.

When someone clicks one of the tabs, we’re going to fade out the old tab’s content and then fade in the content of the new tab. Although we’re using a fade, there’s no reason why we couldn’t use a more complex animation, such as sliding the tab contents left or right.⁵ However, a simple fade animation will more clearly demonstrate how it works.

Inside the About component, the tab contents are rendered by People and Offices components within distinct routes:

import { NavLink, Redirect, Route, Switch } from 'react-router-dom'
import './About.css'
import People from './People'
import Offices from './Offices'

const About = () => (
  <div className="About">
    <div className="About-tabs">
      <NavLink
        to="/about/people"
        className="About-tab"
        activeClassName="active"
      >
        People
      </NavLink>
      <NavLink
        to="/about/offices"
        className="About-tab"
        activeClassName="active"
      >
        Offices
      </NavLink>
    </div>
    <Switch>
      <Route path="/about/people">
        <People />
      </Route>
      <Route path="/about/offices">
        <Offices />
      </Route>
      <Redirect to="/about/people" />
    </Switch>
  </div>
)

export default About

We need to animate the components inside the Switch component. We’ll need two things to do this:

• Something to track when the location has changed

• Something to animate the tab contents when that happens

How do we know when the location has changed? We can get the current location from the useLocation hook from react-router-dom:

const location = useLocation()

Now on to the more complex task: the animation itself. What follows is quite a complex sequence of events, but taking time to understand it is worth it.

When we are animating from one component to another, we need to keep both components on the page. As the Offices component fades out, the People component fades in.⁶ We can do this by keeping both components in a transition group. A transition group is a set of components, some of which are appearing and others are disappearing.

We can create a transition group by wrapping our animation in a TransitionGroup component. We also need a CSSTransition component to coordinate the details of the CSS animation.

Our updated code wraps the Switch in both a TransitionGroup and a CSSTransition:

import {
  NavLink,
  Redirect,
  Route,
  Switch,
  useLocation,
} from 'react-router-dom'
import People from './People'
import Offices from './Offices'
import {
  CSSTransition,
  TransitionGroup,
} from 'react-transition-group'

import './About.css'
import './fade.css'

const About = () => {
  const location = useLocation()

  return (
    <div className="About">
      <div className="About-tabs">
        <NavLink
          to="/about/people"
          className="About-tab"
          activeClassName="active"
        >
          People
        </NavLink>
        <NavLink
          to="/about/offices"
          className="About-tab"
          activeClassName="active"
        >
          Offices
        </NavLink>
      </div>
      <TransitionGroup className="About-tabContent">
        <CSSTransition
          key={location.key}
          classNames="fade"
          timeout={500}
        >
          <Switch location={location}>
            <Route path="/about/people">
              <People />
            </Route>
            <Route path="/about/offices">
              <Offices />
            </Route>
            <Redirect to="/about/people" />
          </Switch>
        </CSSTransition>
      </TransitionGroup>
    </div>
  )
}

export default About

Notice that we pass the location.key to the key of the CSSTransition group, and we pass the location to the Switch component. The location.key is a hash value of the current location. Passing the location.key to the transition group will keep the CSSTransition in the virtual DOM until the animation is complete. When the user clicks one of the tabs, the location changes, which refreshes the About component. The TransitionGroup will keep the existing CSSTransition in the tree of components until its timeout occurs: in 500 milliseconds. But it will now also have a second CSSTransition component.

Each of these CSSTransition components will keep their child components alive (see Figure 2-10).

Figure 2-10. The TransitionGroup keeps both the old and new components in the virtual DOM

We need to pass the location value to the Switch components: we need the Switch for the old tab, and we need the Switch for the new tab to keep rendering their routes.

So now, on to the animation itself. The CSSTransition component accepts a property called classNames, which we have set to the value fade. Note that classNames is a plural to distinguish it from the standard className attribute.

CSSTransition will use classNames to generate four distinct class names:

• fade-enter

• fade-enter-active

• fade-exit

• fade-exit-active

The fade-enter class is for components that are about to start to animate into view. The fade-enter-active class is applied to components that are actually animating. fade-exit and fade-exit-active are for components that are beginning or animating their disappearance.

The CSSTransition component will add these class names to their immediate children. If we are animating from the Offices tab to the People tab, then the old CSSTransition will add the fade-enter-active class to the People HTML and will add the fade-exit-active to the Offices HTML.

All that’s left to do is define the CSS animations themselves:

.fade-enter {
    opacity: 0;
}
.fade-enter-active {
    opacity: 1;
    transition: opacity 250ms ease-in;
}
.fade-exit {
    opacity: 1;
}
.fade-exit-active {
    opacity: 0;
    transition: opacity 250ms ease-in;
}

The fade-enter- classes use CSS transitions to change the opacity of the component from 0 to 1. The fade-exit- classes animate the opacity from 1 back to 0. It’s generally a good idea to keep the animation class definitions in a separate CSS file. That way, we can reuse them for other animations.

The animation is complete. When the user clicks a tab, they see the contents cross-fade from the old data to the new data (Figure 2-11).

Figure 2-11. The contents of the tab fade from offices to people

Discussion

Animations can be pretty irritating when used poorly. Each animation you add should have some intent. If you find that you want to add an animation just because you think it will be attractive, you will almost certainly find users will dislike it. Generally, it is best to ask a few questions before adding an animation:

• Will this animation clarify the relationship between the two routes? Are you zooming in to see more detail or moving across to look at a related item?

• How short should the animation be? Any longer than half a second is probably too much.

• What is the impact on performance? CSS transitions usually have minimal effect if the browser hands the work off to the GPU. But what happens in an old browser on a mobile device?

You can download the source for this recipe from the GitHub site.

Problem

Most applications need to prevent access to particular routes until a person logs in. But how do you secure some routes and not others? Is it possible to separate the security mechanisms from the user interface elements for logging in and logging out? And how do you do it without writing a vast amount of code?

Solution

Let’s look at one way to implement route-based security in a React application. This application contains a home page (/), it has a public page with no security (/public), and it also has two private pages (/private1 and /private2) that we need to secure:

import React from 'react'
import './App.css'
import { BrowserRouter, Route, Switch } from 'react-router-dom'
import Public from './Public'
import Private1 from './Private1'
import Private2 from './Private2'
import Home from './Home'

function App() {
  return (
    <div className="App">
      <BrowserRouter>
        <Switch>
          <Route exact path="/">
            <Home />
          </Route>
          <Route path="/private1">
            <Private1 />
          </Route>
          <Route path="/private2">
            <Private2 />
          </Route>
          <Route exact path="/public">
            <Public />
          </Route>
        </Switch>
      </BrowserRouter>
    </div>
  )
}

export default App

We’re going to build the security system using a context. A context is where data can be stored by a component and made available to the component’s children. A BrowserRouter uses a context to pass routing information to the Route components within it.

We’re going to create a custom context called SecurityContext:

import React from 'react'

const SecurityContext = React.createContext({})

export default SecurityContext

The default value of our context is an empty object. We need something that will add functions into the context for logging in and logging out. We’ll do that by creating a SecurityProvider:

import { useState } from 'react'
import SecurityContext from './SecurityContext'

const SecurityProvider = (props) => {
  const [loggedIn, setLoggedIn] = useState(false)

  return (
    <SecurityContext.Provider
      value={{
        login: (username, password) => {
          // Note to engineering team:
          // Maybe make this more secure...
          if (username === 'fred' && password === 'password') {
            setLoggedIn(true)
          }
        },
        logout: () => setLoggedIn(false),
        loggedIn,
      }}
    >
      {props.children}
    </SecurityContext.Provider>
  )
}

export default SecurityProvider

The code would be very different in a real system. You would probably create a component that logged in and logged out using a web service or third-party security system. But in our example, the SecurityProvider keeps track of whether we have logged in using a simple loggedIn Boolean value. The SecurityProvider puts three things into the context:

• A function for logging in (login)

• A function for logging out (logout)

• A Boolean value saying whether we have logged in or out (loggedIn)

These three things will be available to any components placed inside a Security​Pro⁠vider component. To allow any component inside a SecurityProvider to access these functions, we’ll add a custom hook called useSecurity:

import SecurityContext from './SecurityContext'
import { useContext } from 'react'

const useSecurity = () => useContext(SecurityContext)

export default useSecurity

Now that we have a SecurityProvider, we need to use it to secure a subset of the routes. We’ll create another component, called SecureRoute:

import Login from './Login'
import { Route } from 'react-router-dom'
import useSecurity from './useSecurity'

const SecureRoute = (props) => {
  const { loggedIn } = useSecurity()

  return (
    <Route {...props}>{loggedIn ? props.children : <Login />}</Route>
  )
}

export default SecureRoute

The SecureRoute component gets the current loggedIn status from the Security​Con⁠text (using the useSecurity hook), and if the user is logged in, it renders the contents of the route. If the user is not logged in, it displays a login form.⁷

The LoginForm calls the login function, which—if successful—will re-render the SecureRoute and then show the secured data.

How do we use all of these new components? Here is an updated version of the App.js file:

import './App.css'
import { BrowserRouter, Route, Switch } from 'react-router-dom'
import Public from './Public'
import Private1 from './Private1'
import Private2 from './Private2'
import Home from './Home'
import SecurityProvider from './SecurityProvider'
import SecureRoute from './SecureRoute'

function App() {
  return (
    <div className="App">
      <BrowserRouter>
        <SecurityProvider>
          <Switch>
            <Route exact path="/">
              <Home />
            </Route>
            <SecureRoute path="/private1">
              <Private1 />
            </SecureRoute>
            <SecureRoute path="/private2">
              <Private2 />
            </SecureRoute>
            <Route exact path="/public">
              <Public />
            </Route>
          </Switch>
        </SecurityProvider>
      </BrowserRouter>
    </div>
  )
}

export default App