What Drupal and GraphQL do well

At Amazee Labs, we build decoupled web applications using GraphQL and Drupal. We’ll touch on the reasons that we use this approach in this article, but if you’d like to know more, check out these blogs:

• Introduction to GraphQL
• Don’t Push it: Using GraphQL in Twig
• Graph QL with Twig: Questions and Answers

Drupal is known for its complex and unwieldy theming and rendering system. Data to be rendered comes from across the system in the form of templates, overrides, preprocess functions and contributed modules such as Panels and Display Suite. Sometimes trying to track down where data is being generated or altered is like a murder mystery. 

Thankfully, GraphQL Twig simplifies the situation massively. Each template has an associated GraphQL query fragment that requests the necessary data. This “pull” model (as opposed to Drupal’s normal “push” model) means that finding where the data comes from and how it is structured is really easy. We don’t need to worry about preprocessing or alteration of data, and this method lets us keep the concerns separated.

Advantages of UI component libraries

The main advantage of using a UI component library (also known as a pattern library) is that it facilitates the reusability of components. This means that when a component is created it can be used by any developer on the project to build their parts of the front end and in turn can be used to make larger and more complex components.

There are multiple extra advantages to this, the most obvious being the speed of development. Since all components are simply made up of smaller components, building new ones is usually much quicker, since we don’t need to reinvent the wheel.

This also makes maintenance a breeze, since we’re only maintaining one version of any component. If we decide that all buttons on the frontend need to have an icon next to the text, we simply change the button component and this change will apply everywhere that the component is used.

Finally, the reusability of components in a pattern library means that the UI is consistent. Often, web projects face difficulties where there are multiple versions of various components, each with their own implementation. This is especially true of larger projects built by multiple people, or even multiple teams, where no single person knows the entirety of the project’s implementation details. Thanks to the reusability of our components, we only have one implementation per component.

Challenges of using Drupal, GraphQL, and Storybook together

If done poorly, using pattern libraries like Storybook can be difficult and cause problems during the integration phase(s) of development. The main issue is usually that the frontend and backend developers have different approaches and different goals when developing. 

The frontend developer wants to create the best UI they can in the most efficient way possible, using the paradigms and approaches that are standard or preferred. Unfortunately, at times the implementation doesn’t sync well with the data structure that the backend developers receive from Drupal, so the frontend needs to be refactored or the data structure needs to somehow be altered.

How to make it work

I won’t go into detail on our implementation of the Storybook library, but we keep Storybook in the same repo as our Drupal application, outside the root. We then define a base storybook theme and using the Components module (built by my talented colleague John Albin), we define our path to the Storybook Twig templates as a component library in our .info.yml file. This way, the Drupal theme has access to all of our templates.
 

component-libraries:
  storybook:
    paths:
      - ../../../../storybook/twig

We then create our project-specific theme, which extends the base Storybook theme, and start to work on our integration. A generic page.html.twig file might look like this:
 

{#graphql
query {
  ...Header
  ...Footer
}
#}
{% extends '@storybook/page/page.html.twig' %}

{% block header %}
  {% include '@storybook/navigation/header.html.twig' with graphql only %}
{% endblock %}

{% block content %}
  {{ page.content }}
{% endblock %}

{% block footer %}
  {% include '@storybook/footer/footer.html.twig' with graphql only %}
{% endblock %}

So, how does GraphQL tie in here? Well, this is the really clever part. Our developers can create the GraphQL snippets to get the data needed for a specific component, and Storybook allows us to use JavaScript to use this data as mock fixtures. This means that the frontend can be built with realistically structured data, so no refactoring of templates or data alteration on the backend is needed. And since we already have the GraphQL snippet, this automatically works when run in Drupal. 

Conclusion

At Amazee, we use a UI component library because it makes sense to build a maintainable, reusable and consistent set of components for our frontend that also encourages faster development. We also try our best to streamline our integration processes so that all of our developers are more closely aligned and developing solutions that make it easier for their colleagues to use, learn and extend easily. 

Storybook gives us the power to build a component library using mock data that is structured in the exact manner that our GraphQL queries deliver it. This means no refactoring, building both queries and templates only once and an overall smooth integration process. 

Want to know more about using GraphQL and Twig? Check out our webinar!