Get Started Using React and Drupal Together

React is a JavaScript library that makes it easy to create interactive user interfaces. Drupal is a content management system with a powerful web services API. There are a couple of different ways that React and Drupal can be used together. This series of tutorials explores some of those options, and the related concepts and terminology.

Our goal with this series is to provide you with some baseline information you can use to get started integrating React and Drupal together. We'll cover using React to to provide UX enhancements as part of an existing Drupal theme. As well as how to create a fully decoupled system that uses React for the frontend, and Drupal for the backend.

After you've completed these tutorials you should be able to better envision how to use these two amazing technologies to solve some of your own issues. And to explore further on your own. We link to additional resources liberally, and encourage you to explore beyond the examples we provide, read the linked resource, and dig in. There's no substitute for exploration, and experimenting with real code when it comes to learning.

What you'll learn

  • An introduction to the technical side of React, terminology, and information about where to find more resources
  • Learn about using Drupal, and the JSON API module, to turn Drupal into a powerful web services API provider
  • Learn about the use-cases for adding React to a Drupal site
  • Walk through increasingly complex code examples that start with a "Hello World!" application, and end with a fully decoupled application that can list, create, update, and delete content in Drupal
  • Learn about how to authenticate a Drupal user via an API using React
  • Compare the differences between integrating React into an existing Drupal theme or module and creating a stand-alone React application through example code and use-cases
  • And more...

This series is for developers

This series is for developers who want to get their hands on some code and who learn best by doing. We're assuming that you already have a basic understanding of Drupal administration and are comfortable with doing things like creating content and users, installing modules, and configuring your application. We also expect that you're already familiar with JavaScript.

Need to brush up first?

Tutorial

Introduction to React and Drupal

Free
Theming, Module Development, Drupal 8, Drupal 9, Drupal 10
More information

React is a JavaScript library that makes it easy to create interactive user interfaces. Drupal is a content management system with a powerful web services API. React and Drupal can work together in a couple of different ways. This series of tutorials explores some of those options, and the related concepts and terminology.

Tutorial

React Basics

Theming, Module Development, Drupal 8, Drupal 9, Drupal 10
More information

Before we start writing any React code, let's go over some basic concepts and terminology. Throughout this series we'll assume you're familiar with these things. They'll come up again and again as you work on projects that involve React, so it's worth taking the time to learn them.

In this tutorial we'll cover the following at a high level, and provide links to resources:

Tutorial

Decoupled vs. Progressively Decoupled

Theming, Module Development, Drupal 8, Drupal 9, Drupal 10
More information

React and Drupal can be used together in two different ways: fully decoupled, also known as headless; or progressively decoupled.

In this tutorial we'll talk about the differences between these two approaches, including:

  • Defining what each method refers to
  • Considerations regarding hosting, performance, and access

Then we'll link to lots of additional reading materials so you can gain a deeper understanding of the subject.

Tutorial

Connect React to a Drupal Theme or Module

Free
Theming, Module Development, Drupal 8, Drupal 9, Drupal 10
More information

Writing a React application requires including the React JavaScript library in the page, writing some React-specific JavaScript, and then binding it to a specific DOM element on the page. You may also want to include existing packages from the npm ecosystem, and use modern JavaScript (ES6+) features, which necessitates setting up a build toolchain for your JavaScript using a tool like Webpack or Parcel.

Tutorial

Create a React Component

Theming, Module Development, Drupal 8, Drupal 9, Drupal 10
More information

Components are the fundamental building blocks of any React application. React uses components to represent different elements in the UI. To show this, we'll build a React widget that can query the Drupal.org REST API to retrieve usage statistics for a project and then display them. We'll create buttons that allow us to toggle between two different projects. In doing so we'll learn about creating components and using props and state in React.

In this tutorial we'll:

Tutorial

Add Webpack Hot Module Replacement (HMR) to a Drupal Theme

Theming, Module Development, Drupal 10, Drupal 9, Drupal 8
More information

Hot Module Replacement (HMR) is a technique for using Webpack to update the code that your browser renders without requiring a page refresh. With HMR configured it's possible to edit your JavaScript (and CSS) files in your IDE and have the browser update the page without requiring a refresh, allowing you to effectively see the results of your changes in near real time. If you're editing JavaScript or CSS it's amazing. And, it's one of the reasons people love the developer experience of working with React so much.

Tutorial

Retrieve Data from an API with React

Theming, Module Development, Drupal 8, Drupal 9, Drupal 10
More information

React excels at displaying lists of data. But that data needs to come from somewhere. In most cases this happens by making a network request to retrieve data from one or more APIs, processing the response, and then displaying the data. In the context of working with a Drupal site there are two possible options: Drupal core's JSON API module, or the drupalSettings JavaScript API.

In this tutorial we'll focus on the high-level overview and:

Tutorial

Use React to List Content from Drupal

Theming, Module Development, Drupal 8, Drupal 9, Drupal 10
More information

In order for our React code to list content from Drupal we'll need to enable the Drupal core JSON:API module, and then use fetch() in our React component to retrieve the desired data. This technique works for both React code embedded in a Drupal theme or module, and React code that is part of a fully decoupled application. We'll discuss the differences between those styles as well.

In this tutorial we'll:

Tutorial

Create, Update, and Delete Drupal Content with JavaScript

Theming, Module Development, Drupal 8, Drupal 9, Drupal 10
More information

To perform create, update, and delete (CRUD) operations with Drupal core's JSON:API via React there are a few things you'll need to understand. First, how to format the POST, PATCH, and DELETE requests necessary to add, edit, and delete Drupal entities. Next, how to handle authentication, and cross-site request forgery (CSRF) tokens. Over the next few tutorials we will create a simple but powerful React application that can add, edit, and delete Drupal node content.

This tutorial contains:

Tutorial

Build an Interface to Edit Nodes with React

Theming, Module Development, Drupal 8, Drupal 9, Drupal 10
More information

Using React we can do more than just list content. By using the POST, PATCH, and PUT methods of Drupal core's JSON:API web service we can also add, update, and delete, content entities. To demonstrate how this works we'll create a small React application with a form that lets you add, edit, and delete article nodes.

In this tutorial we'll:

Tutorial

Create a Fully Decoupled React Application

Free
Theming, Module Development, Drupal 8, Drupal 9, Drupal 10
More information

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:

Tutorial

Use create-react-app to Start a Decoupled React Application

Theming, Module Development, Drupal 8, Drupal 9, Drupal 10
More information

Using create-react-app we can scaffold a stand-alone React application with boilerplate configuration and organization already in place. It's a great way to get started using React, as well as the ecosystem of associated tools like Webpack, Jest, and Babel. After creating the scaffolding, we'll port the code we wrote in previous tutorials to the new structure.

In this tutorial we'll:

Tutorial

Make API Requests with OAuth

Theming, Module Development, Drupal 8, Drupal 9, Drupal 10
More information

When you create a fully decoupled application, the code in your application can't rely on things like the fetch() function's same-origin policy and the browser's use of cookies to authenticate requests. Instead, you need to use alternative methods like OAuth or JSON Web Tokens (JWTs).

We'll focus on setting up and using Drupal as an OAuth provider, and allowing a decoupled application to authenticate users via OAuth. This same technique applies just as well if you want to use JWTs.

In this tutorial we'll:

Tutorial

Use Fetch and OAuth to Make Authenticated Requests

Theming, Module Development, Drupal 8, Drupal 9, Drupal 10
More information

To perform POST, PUT, and DELETE operations to Drupal's JSON:API via a decoupled React application we need to use an OAuth access token. This requires first fetching the access token from Drupal, and then including it in the HTTP Authorization header of all future requests. We'll also need to handle the situation where our access token has expired, and we need to get a new one using refresh token.