Last updated March 7, 2019

Now that we know how to build a working application in React, and embed the application in Drupal, let's make a stand-alone version of our application, which can be used outside of the context of a Drupal module or theme. In the next few tutorials we'll look at how to create a fully decoupled React application whose only interactions with Drupal happen via API requests.

In this tutorial we'll:

  • Introduce differences we need to account for in a fully decoupled application
  • Provide an example of what the final project will look like

By the end of this tutorial you should have a better understanding of what we're trying to accomplish in the rest of this course.

Goal

Understand the modifications needed to build a stand-alone version of our React application.

Prerequisites

The remaining tutorials build on the code for the progressively decoupled React application created in the previous tutorials. If you're just starting from here you'll want to make sure you grab that example code as a starting point.

Download the sample code

Overview

In the previous tutorial, we built a "progressively decoupled" React application. This means we embedded the React application inside Drupal. We connected to the JSON API and used the same-origin cookie to send authenticated API requests from the API that the Drupal site provided. This allowed us to side-step some things that we'll now have to account for in our code. Most of these things are primarily related to authentication. Our previous code relied on the fact that it was essentially running inside the scope of an existing Drupal theme or module, and could therefore make use of existing cookie and session handling for authentication. If you were logged into Drupal, you were also logged into our React app. For a fully decoupled application, we'll have to handle all of that ourselves.

In order to accomplish this we'll want to start using OAuth to handle authentication and authorization. With OAuth, we're happily no longer dependent on the browser's somewhat opaque handling of cookies for authentication. Therefore, our code will work in other contexts, for example, a React Native app where the code isn't executed inside a browser. The downside is we'll have to write a bunch of code to handle something the browser had been doing for us automatically.

You can use this same approach with any JavaScript front-end framework -- it's not specific to React. In fact, you can use this same approach with any decoupled application that needs to communicate via HTTP with Drupal. This opens doors to all kinds of possibilities. It doesn't even have to be JavaScript.

Benefits of a decoupled React application

The primary benefit, as far as writing code goes, is that it's much easier to follow best practices established by the React community. This can go a long way towards helping find useful documentation, or even getting help from others, when working on your code base.

When you introduce a build tool to your React code, you get many benefits for development. You can code with hot-reloading, where your JavaScript will update automatically in the browser whenever you save the file. You can use linting tools with your code editor to write cleaner code. You can use a variety of CSS preprocessing tools. You can break up your React code into files for each component, and use that to organize your application in a sensible way.

You can also more easily leverage third party packages. When you set up a build tool, you can import packages into React from npm. With a progressively decoupled application, you might be able to add some JavaScript libraries to your page in the HTML headers, but this can quickly get cumbersome. With a decoupled application and a working build tool, you can load libraries into components only when you need them. Your application will be self-contained.

What we're building

This tutorial will cover how to set up build tools to compile a React application and allow for development processes that more closely match what JavaScript developers are used to. We will use the create-react-app application to scaffold a new project, then port our existing code into that framework.

On the Drupal side, we'll install and configure the Simple OAuth module to allow for making authenticated requests to the JSON API module. This will allow our decoupled React application to do things like POST, PATCH, and DELETE content in Drupal. Doing so will require us to refactor some of the HTTP request code to handle OAuth tokens.

Finally, we'll demonstrate how we can improve the UI of our application using a UI framework adapted to integrate with React. We'll add the Google Material UI to our project, and make use of its UX components in our code to give things a little more style and animation.

Let's get started

Start with create-react-app Use create-react-app to scaffold a new fully decoupled React codebase. Optionally, learn how to integrate that into a Drupal theme or module.

Make API requests with OAuth Learn how to configure the Simple OAuth Drupal module and use a password grant flow to create authenticated API requests.

Use Fetch and OAuth to Make Authenticated Requests Add a login form to collect a username and password, exchange those for an OAuth access token, and update existing fetch requests to use the OAuth access token.

Extend React with Google Material UI Use yarn or npm to add third party JavaScript libraries to your project. In this example we'll add the Google Material UI package which contains UX components that can incorporate into our application to give it a more "Material UI" feel without having to write much additional code.

Further your understanding

  • Make a list of the changes you think you'll need to make in order to fully decouple your application

Additional resources

You won't need to understand all the build tools for these tutorials, but if you are curious and want to understand some of the terms you might come across, here are some good introductory articles: