How we jumped head-first into decoupling Drupal with a React-based design system built for performance and brand consistency.

It’s funny how things go. As a company, we’re constantly working in Drupal: building, planning, and helping to maintain various modules and websites for both our clients and the Drupal community. While the large majority of our clients and work is in the latest version of Drupal, our site is still running Drupal 7. Shame on us, right! Like many businesses out there, it’s easy to push aside the upgrade when our internal systems and staff are comfortably using the existing platform and everything is working like a well-oiled machine. Well, we finally got the buy-in we needed from our internal stakeholders and we were off to the races. But, we didn’t want just another Drupal website. We wanted to explore the “bleeding edge” and see if we can achieve the holy grail of web development — a CMS-driven back end, with a modern, decoupled javascript front end using a component-based design system. Go big or go home!

Our approach to the back end

After a solid planning phase, we settled on an approach for the new site build and it was time to get going. We decided on Drupal (of course) for the back end since it’s our CMS of choice for many reasons and we could leverage all of the great work that has already been done with the JSON:API. However, not all of our needs were covered out-of-the-box.

Exploring API-first distributions

When we were first getting started, we spent some time looking at using ContentaCMS for our back end. It’s an API-first Drupal distribution that already contains most, if not all, of the modules we needed. Ultimately, we decided against it due to the number of extra modules that were unnecessary for our build. We also knew we wanted to use Paragraphs and Layout Builder, but found some display width issues that didn’t line up with our vision. We ditched ContentaCMS and went back to a fresh Drupal 9 install with just the modules we needed.

Decoupled menus

Another complication we came across focused around decoupled menus. Obviously, to build out a menu on the front end we needed to be able to get menu items. JSON:API Menu Items was installed and gave us a good starting point by exposing the menus in JSON:API. Next, we needed to get around the fact that JSON:API relies on UUID for content but menus use paths. Content also likes to have pretty URLs to use for navigation via path aliases. To display these path aliases from the front end and be able to retrieve the correct node, we need some way to resolve the path alias to its correct content. In comes the Decoupled Router module to solve the problem for us! This module provided the endpoints we needed.

Simplifying the JSON output

When you first install JSON:API, you get all of the data. While this is great, it negatively affects the developer experience by making it harder to find the data you need. JSON:API Extras was critical in improving this experience. With this module, we can easily remove unnecessary fields and customize our API path exactly how we want it. We also used the OpenAPI module to give developers a better high-level look at the available endpoints and their structure, opposed to looking at gross JSON output.

Our approach to the front end

With our back end sorted out, it’s time to get to the front end. When going decoupled, the front end suddenly becomes a whole lot more interesting than just a standard Drupal theme with Twig templates, SASS stylesheets and jQuery. We’re in a whole different realm now with new possibilities. We were 100% on board with having better integration between design and development, where the end result of the design was more than static assets and a 1-hour handoff. Here’s a breakdown of our front end approach.

A new strategy for consistency between design in development

In the past, creative exercises would provide static assets such as style guides to try and capture the design principles of a web property or brand. While this concept is rooted in good intentions, in practice, it never really worked well as a project evolved. It’s simply too difficult to keep design and development in sync in this way. For web development, it’s now understood that the code is a better source of truth, not a style guide, but we still need ways to involve our designers and have them contribute their knowledge of design and UX into the code that is being developed. After all, if you leave these decisions up to developers, you’re not going to end up in a good place (and most developers will readily agree with that sentiment). Luckily for us, applications like Figma, Sketch, and Adobe XD, are leading the way to bridge this gap. While this is still very new territory, there is a lot of exciting progress happening that is enabling the creation of robust design systems that act as a rulebook and single source of truth that is both easily updated, modular, and readily available for product application development.

After an internal study of available technologies for design, we settled on Figma for our design system creative work. Figma runs in either web or desktop applications and is a vector graphic editor and prototyping tool. The team developing it has done an incredible job pushing the envelope on how creative and development can work together. With Figma, we found it was possible to accomplish the following:

Extracting design tokens into our application

With our tokens living in Figma, we still needed a way to bring those static design token values into our development process. This is where Figmagic comes in. Figmagic is a nice tool for extracting design tokens and graphic assets out of Figma and into our application. Once set up, all we need to do in our local development environment is to run yarn figmagic. This connects to Figma and pulls down all of our defined tokens into an organized set of ready-to-use files. From there, we then simply import the file we need into our component and use the values as required. If a value needs to change, this is done in Figma. Re-running Figmagic brings in any updated value which updates any component using it. It works like... magic.

Building reusable front end components

Going decoupled meant breaking away from Drupal’s Twig templating and theming layer. For our front end application, we decided on React for our replacement. React continues to be very popular and well-liked, so we didn’t see any technical advantage to picking anything else. This change brought on some additional challenges in that, as a Drupal development company, our focus has not been React. We undertook some initial training exercises to get our development team on this project up-to-speed with the basics. Between this team, our CTO, our CXO, and a senior technical lead, we quickly trained up and settled on a suite of tools to achieve our desired outcomes of a component-driven React frontend.

Component UI frameworks to increase velocity

For us, the approach to developing the many React components that we needed was to first settle on an established framework. Like Bootstrap is to HTML/CSS development, several React-based frameworks are available to use as a foundation for development. It’s always debatable whether this is necessary or not, but we felt this was the best way for us to get started as it greatly increases the development velocity of our project while also providing good reference and documentation for the developers creating our components. We researched several and tried a few, but eventually found ourselves leaning towards Material UI. There were several reasons for this decision, but mainly we like the fact that it is an established, proven, framework that is flexible, well documented, and well supported. With Material UI (MUI), adjusting the base theme using our design tokens from Figma already gave us a good start. Its framework of pre-built components allowed us to make minimal changes to achieve our design goals while freeing up time to focus on our more unique components that were a bit more custom. This framework will continue to be of great benefit in the future as new requirements come up.

Previewing design system component without Drupal

Without a standard Drupal theme available, we needed somewhere to be able to preview our React components for both development and UX review. A decoupled front end, and the whole point of the design system, is that the front end should be as back end agnostic as possible. Each component should stand alone. The front end is the front end and the back end could be anything. Since we haven’t yet connected the front end components to Drupal’s JSON:API, we still needed an easy way to view our design system and the components within it. For this, we used Storybook. Storybook was made for developing and previewing UI components quickly. As a developer working locally, I install and spin up an instance of Storybook with a single command within our project repo. Storybook then looks at our project folder structure, finds any story files that we include as part of all of the components we develop, and generates a nice previewer where we can interactively test out our component props and create examples that developers in the future may need when implementing a component. Storybook is our design system library and previewer as well as our developer documentation. When we are done developing locally and push code to our repository, our deployment pipeline builds and deploys an updated Storybook preview online.

Bringing it all together

At this point, we have our back end and API established. We also have our front end component library created. Now we need to bring it all together and actually connect the two.

Matching the Drupal UI to our React components

React components are standalone UI elements and are made up of props that determine their functionality. So, for instance, a Button component could have many variants for how it looks. A button could include an icon before or after the text, or it could be used to open a link or a dialogue window, etc. A simple component like this might have a whole bunch of different props that can be used in different ways. To be able to control those props through the Drupal UI, we decided to use the Paragraphs module. A paragraph in Drupal is essentially a mini content type for a specific use. In Drupal, we created paragraphs that matched the functionality we needed from our React components so that the Drupal UI would be, in the end, setting the component props. This is a bit confusing to set up at first and something that will probably not be nailed down first try, but, in the process of setting up the Drupal UI in the context of the React components, you can really start to see how the connection between the two is made. At this point, it’s pretty easy to see if a component is missing any props or needs to be refactored in some way.

We also went with Paragraphs because we wanted to give our content creators a more flexible way of creating content. A standard Drupal content type is pretty rigid in structure, but with Paragraphs, we can give content creators a set of building blocks that can be grouped and combined in many different ways to create a wide variety of pages and layouts in a single content type. If you’re not familiar with this style of creating content in Drupal, I suggest you take a look at this post I wrote a while back. Look at that and imagine React components rendering on the page instead of Drupal templates. That’s essentially what we’re aiming to do here.

An argument against Paragraphs is that it could potentially make page building more time-consuming given that you don’t have that typical rigid structure of a content type. This is especially true if pages on a site being built typically all follow a similar format. In this case, we still like to use Paragraphs anyway but we will typically build out unpublished pages that act as templates. We then install the Replicate module which lets content creators clone the template and use it as a starting point. This makes creating pages easy and consistent while still allowing flexibility when needed. Win-win.

Taking the Next.js step

Since we settled on React, we started our front end project as a standard react build using the built-in create-react-app command. But, after some additional investigation, we decided that a better option for our use case would be to use the Next.js framework. Given that the corporate site is, at its core, is a marketing and blogging website, Next.js allows us to still build the frontend using React but gives us some extra capabilities this type of website needs.

One of these capabilities is incoming server-side rendering which we found increases the performance of our application. This also has SEO benefits due to pages being rendered serverside and sent to the client, as opposed to the standard client-side rendering most React applications use where the client machine handles processing and rendering.

Component factories are key to interpreting the API data

We were also attracted to the structure and organization of the project when using a framework like Next.js, as well as the dynamic routing capabilities. This significantly simplified the code required to implement our decoupled menu and page routing. Using the dynamic routes provided by Next.js, we could create “catch-all” routes to handle the ever-growing content in the CMS. By querying the Drupal API, we can get all the available path aliases for our content and feed it to Next.js so it can pre-build our pages. It can use the path aliases to resolve the content specific to the page through the Decouple Router module, which will then feed that data to a component factory to handle the decision as to what high-level React page component is necessary to build a page. For example, if the data is for a basic page content type, the page factory component returns our Page component, if it’s a blog post content type, it returns the Blog Page component, etc. Each of these components knows how to handle the specific data fed to it, but the factory component is what connects the data to the right page.

The way Paragraphs can be added to a page for composing a piece of content also created a challenge on its own in reading that data and returning the right component. We decided to create another factory component for this. Similar to the page factory component, this one takes in the paragraph data and determines which React components it needs to render the content.

What’s next in our decoupled adventure

Believe it or not, what we’re building is still a work in progress. While we have most of the tech requirements figured out, we’re still actively putting all of the final pieces in place and fine-tuning the backend UI and modules requirements. All in all, we’re feeling really good about this progress and can see the value of what we’re building both for ourselves and the clients we serve. In our opinion that is based on experience and research, decoupled is the future, and we’re excited to walk this path.

With that said, even once our own decoupled site has launched, we still have a lot of work left to do. For one, we still need to get a method in place for managing Drupal blocks and regions. More factory components will be critical here to interpret that data. Given that our clients are primarily ecommerce retailers in one form or another, we still have the whole ecommerce side of web development to sort out, including product catalogues, add-to-cart forms, carts, wish lists, checkout flows, etc. The list is long. However, what we have is a framework that can be repurposed and added on to. It finally helps tie together many disciplines of web development, both creative and technical, that are traditionally siloed. It’s also blazing fast and just plain cool. This is an investment not only in our own online business front but in something greater that we hope to share with others through work, community and general knowledge.

Thanks for taking the time to read this. If you want to chat about this initiative further, drop us a line.