Problem

React projects are difficult 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 reasonable 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 --typescript my-app

Facebook developed create-react-app, so it should come as no surprise that your new project uses the yarn package manager. To use npm, change into the directory and remove the yarn.lock file, and then re-run the install with npm:

cd my-app
rm yarn.lock
npm install

To start your application, you should run the start script:

npm run start # or yarn start

This command launches a server on port 3000, and opens a browser at the home page:

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 * as serviceWorker from './serviceWorker';

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

// If you want your app to work offline and load faster, you can change
// unregister() to register() below. Note this comes with some pitfalls.
// Learn more about service workers: https://bit.ly/CRA-PWA
serviceWorker.unregister();

This file does little more than render a single component called <App/>, which is imported from App.js in the same directory:

import React from 'react';
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 in there generates a set of static files:

├── asset-manifest.json
├── favicon.ico
├── index.html
├── logo192.png
├── logo512.png
├── manifest.json
├── precache-manifest.04a2f4deb0e98d3c8eb66908edce9f33.js
├── robots.txt
├── service-worker.js
└── static
....├── css
....├── js
....└── media

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 randomized 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 re-running npm install. You don’t need to manage a list of babel plug-ins, postcss libraries, or maintain a complex webpack.config.js file. The react-scripts library manages them all for you.

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 --typescript flag 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 do 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 proxy 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 web site 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 lower than, say, those built with create-react-app.

Gatsby has a large number of plug-ins that can load and transform data efficiently from static local data, GraphQL sources, and third-party CMS 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

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

Gatsby projects have a straightforward structure:

├── LICENSE
├── README.md
├── gatsby-browser.js
├── gatsby-config.js
├── gatsby-node.js
├── gatsby-ssr.js
├── node_modules/
├── package-lock.json
├── package.json
└── src
....├── components
....├── images
....└── pages

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:

import React from "react"
import { Link } from "gatsby"

import Layout from "../components/layout"
import Image from "../components/image"
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>
    <div style={{ maxWidth: `300px`, marginBottom: `1.45rem` }}>
      <Image />
    </div>
    <Link to="/page-2/">Go to page 2</Link> <br />
    <Link to="/using-typescript/">Go to "Using TypeScript"</Link>
  </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 a lot of 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 1389 bytes long and 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.

Secondly, 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, which is 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 in case it needs to generate some dynamic content.

This file structure means that Gatsby pages load in around the same time that it takes to load a static web page. 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.

Discussion

How will the content get into your Gatsby application? You might use a headless CMS system, a GraphQL service, a static data source, or something else. Fortunately, Gatsby has many plug-ins which allow you to connect data sources to your application, and then transform the content from a format such as Markdown into HTML.

You can find a full set of plug-ins on the Gatsby web site.

Most of the time, you choose the plug-ins 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 above uses the default started template, which is quite simple. The gatsby-config.js file in the root of the application configures which plug-ins your application uses.

But there are masses of Gatsby starters available, pre-configured to build applications that connect to a variety of data sources, with pre-configured options for SEO, styling, offline caching, PWA (Progressive Web Applications), and more. Whatever kind of content-rich application you are building, there is a starter that is close to what you need.

There is more information on the Gatsby web site 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 main architectural decisions will be. Should you create a SPA? If performance is critical, should you use Server Side Rendering? You will need to decide what your deployment platform will be, and whether you are going to write your code in JavaScript or TypeScript.

Many tools require that you answer these questions early on. If you later change your mind, modifying the way 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: that is, applications that can execute their JavaScript on the server. Or the client. Or both.

Razzle uses a plug-in architecture that allows you to change your mind about how you build your application. It will even let you change your mind about whether you are building your code in React, or 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-3.

Figure 1-3. 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 with node 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 is what 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 a SPA, remove the app/index.js and app/server.js files. Then create an index.html in the public/ folder containing a <div/> with id root, and re-build the application with:

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 plug-ins. Each plug-in is a higher-order function that receives a webpack configuration and returns a modified version. One plug-in 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 plug-ins you use.

You can find a list of available plug-ins on the Razzle web site.

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

Problem

The focus of React is on client code–even if that client code is generated on the server. Sometimes, however, you might have a relatively small amount of 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 that include their own server code. The api end-points and the client pages use default routing conventions, which makes 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 web site.

At the time of writing, you cannot create a Next.js application using npx. Instead, you should first install create-next-app globally:

npm install -g create-next-app

Then, you can generate a new application:

create-next-app my-app

This will create a Next.js application in the my-app subdirectory. To start the app, run the start script:

cd my-app
npm run start

Figure 1-4. A NextJS 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 is used to generate 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 as well.

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

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

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

The routing which mounts this to the end-point api/hello happens automatically.

The code that you write in Next.js is automatically built into a hidden directory called .next/. This code can then be deployed to a service such as Next.js’ own Vercel platform.

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

node_modules/.bin/next export

This will build your client code in a directory called out/. Each page of your site will be converted into a statically rendered HTML file, which will load very quickly in the browser. At the end of the page, it will load the JavaScript version in case the React code needs to modify the DOM.

Next.js comes with a bunch of data-fetching options, which allow you to get data from static content, or via headless 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 useful for teams who will have a small amount of server code that they want to manage simply.

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

Problem

React applications can be large. It’s quite easy to create a simple React application which is transpiled into bundles of JavaScript code that are several hundred Kbs in size. There are times when you might want to build an app with React-like features, but without having to download a large amount of JavaScript code.

Solution

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

Preact is not React. It is a separate library, but it is designed to be as close to React as possible while being much, 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, which is then used to update the actual DOM at frequent intervals. Doing so allows basic DOM-rendering to be fast because the actual DOM only needs to be updated when there are real 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 Server-Side Rendering⁵, but SSR can be complex to configure. Sometimes, you just 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. This 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 really very basic. The core Preact library does not support JSX, and you will have no Babel support and so you will not be able to use modern JavaScript. This 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 id 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". This 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 very least, support modern JavaScript.

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

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

npm install -g preact-cli

Then you can create a Preact application with:

preact create default my-app

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

cd my-app
npm run dev

This will start the server on port 8080, as shown in figure 1-5.

Figure 1-5. 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, for example, looks very react-like, with full JSX support.

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

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⁶ and then run the build script:

npm run build

This will generate a static version of the application in the build/ directory. First of all, this will have the advantage of creating a static copy of the front page, which will render very quickly. Secondly, 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 to React, it provides virtually the same power, at a fraction of the size. And the fact that it can be used for anything between 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 web site.

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

If you would 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 that can be used 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 can be just as tedious as manually creating a project for an entire React application.

Solution

The NWB toolkit can be used to create full React applications, but can also create projects that are specifically intended to create a single React component. In fact, it can also create components for use within Preact and InjernoJS projects, but we shall 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, you will be asked several questions about the type of library you want to build. You will be asked 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 will allow you to build a version including an export statement, which can use by WebPack to decide whether or not the module is required in a client application. You will also be asked if you want to create a Universal Module Definition:

? 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.

This 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-6.

Figure 1-6. 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 reading to create a publishable version, simply type:

npm run build

This will now create a built version of your component 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 HTML pages are rendered on the server in response to browser requests. But sometimes you may want to include more interactive elements inside a Rails application.

Solution

The Webpacker library can be used to insert React applications into Rails generated web pages. To see how it works, let’s first generate a Rails application which includes Webpacker:

rails new my-app --webpack=react

This 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 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. Webpacker applications are inserted 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 the button is clicked.

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

Which will show the page you can see in figure 1-7.

Figure 1-7. A React app embedded in Rails

Discussion

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

Webpacker is intended to be used alongside Rails code, rather than as a replacement of it. It’s useful if your Rails application requires a small amount of additional interactivity.

To 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 useful 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 that can be used in a web page. In effect, they are a way of extending the HTML language by making more tags available to a user.

This recipe looks at how a lightweight framework like Preact can be used to create custom elements, which themselves can be served from a third-party service.

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 --save

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

Next, we need to modify the app/index.js 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/>, which has a single property called currency and which will be built using a component defined in ./components/Converter/index.js, which we will define like this:

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 very simple currency converter, which in our example, is using 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

In order 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 is including the definition of the custom element in the final <script/> of the <head/> element. In order to make sure that the custom element is available across both new and old browsers, we also include a couple of shims from unpkg.com.

Now that the custom element code is included 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, which will be passed through to the underlying Preact component.

We can run this page through a web server, separate from the Preact server. The new custom element is shown in figure 1-8.

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

Discussion

The custom element does not need to be served from the same server as the web page that uses it. This means that custom elements are a way of making embeddable widgets available for online services. Because they can be accessed from elsewhere, 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 can then be placed on any web server, and will likely be significantly smaller.⁹

Think about security. You may want to tie down which domains can access the element by checking the forward header

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

Problem

React components are the stable building material of React applications. If they are written carefully, they can be re-used cleanly within and between React applications. But when you are building components, it is sometimes challenging to create the entire set of circumstances that the component will have to deal with. For example, in an asynchronous application, components might frequently be rendered with undefined properties. Will the component still render correctly? Will they show errors when they’re misused?

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 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 useful if there was 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. It could be described 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 -p @storybook/cli sb init

And then start the Storybook server:

npm run storybook

Storybook runs its own server: in this case, we are running it on port 9000, as you can see in figure 1-9. When you are using Storybook, there is no need to run the actual React application.

Figure 1-9. 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. This is src/stories/1-Button.stories.js:

import React from 'react';
import { action } from '@storybook/addon-actions';
import { Button } from '@storybook/react/demo';

export default {
  title: 'Button',
  component: Button,
};

export const Text = () => <Button onClick={action('clicked')}>Hello Button</Button>;

export const Emoji = () => (
  <Button onClick={action('clicked')}>
    <span role="img" aria-label="so cool">
      ? ? ? ?
    </span>
  </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 take stories with it as a form of living documentation.

Figure 1-10 shows what 1-Button.stories.js looks like inside Storybook.

Figure 1-10. An example story

Discussion

Despite its simple appearance, Storybook is actually a very 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 out 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:

• 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 many, many more.

For further information about Storybook see their web site.

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 inside a real browser, with all of the additional complications that that entails. Traditionally browser testing can be unstable and prone to frequent upgrade problems as browser drivers (such as chromedriver) have to be upgraded every time a browser is.

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 webdriver 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 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 editing the cypress.json file in the application directory, and tell if the URL of our app:

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

Once we have started the main application:

yarn start

We can then open Cypress:

npx cypress open

The first time you run Cypress it will install all of the dependencies it needs. We’ll now create a test in the cypress/integration/ directory called screenshot.js. This will be a very simple test 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 tests are written in Jest format. Once you save the test, it will appear in the main Cypress window, shown in figure 1-11.

Figure 1-11. The Cypress window

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

Discussion

Here are some example commands you can perform with Cypress:

These are just 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–it can even 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 cause any networking code in the application that makes a call to a server endpoint beginning /api/server?... will return the JSON array [{some: 'Data'}].

This can completely change the way times can develop applications because it decouples the front-end development from the back end. The browser tests can specify what they want 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.