How to deploy Gatsby with Drupal (Decoupled Drupal) on Platform.sh

Platform.sh maintains a template that you can quickly deploy, and then use this guide as a reference for the Platform.sh specific changes that have been made to Gatsby and Drupal to make it work. Click the button below to sign up for a free trial account and deploy the project.

Shared configuration

Your local clone of the template has the following project structure:

├── .platform
│   ├── routes.yaml
│   └── services.yaml
├── drupal
│   ├── # App code
│   └── .platform.app.yaml
├── gatsby
│   ├── # App code
│   └── .platform.app.yaml
└── README.md

From this repository, you deploy a Gatsby app and a Drupal app. The code for each of them resides in their own directories. When deploying a single app project such as Gatsby, the repository needs three configuration files that describe its infrastructure, described below in detail. For multi-app projects, two of those files remain in the project root and are shared between Gatsby and Drupal. Each app keeps its own app configuration file (.platform.app.yaml) in its subdirectory.

Service configuration

This file describes which service containers (such as a database) your project should include. Gatsby does not require services to deploy, but Drupal does. So the following examples shows these service configurations:

Routes configuration

This .platform/routes.yaml file defines how requests are handled by Platform.sh. The following example shows Gatsby being served from the primary domain and Drupal being accessible from the backend subdomain.

Drupal

The multi-app template has a single modification to Platform.sh’s standard Drupal template: the name attribute in Drupal’s .platform/services.yaml has been updated to drupal. This value is used to define the relationship between Gatsby and Drupal and in the routes configuration.

The only setup required to prepare the backend is to install a few additional modules that will configure the JSON API for consumption. In your Drupal directory, add the following dependencies.

composer require drupal/gatsby drupal/jsonapi_extras drupal/pathauto

The Pathauto module helps you assign alias paths for each piece of content on your Drupal site that can then be replicated on the frontend Gatsby site. For example, the Drupal alias /article/some-new-article is the same path you find that article at on Gatsby.

Gatsby

The frontend Gatsby app has a slightly different configuration from the basic Gatsby deployment. Below is the gatsby/.platform.app.yaml file that configures the app.

In particular, notice:

• relationships

  Access to another service or app container in the cluster is given through relationships. In this case, one has been defined to the backend Drupal container using it’s name.

• post_deploy

  Platform.sh containers reside in separate build containers at build time, before their images are moved to the final app container at deploy time. These build containers are isolated and so Gatsby can’t access Drupal during the build hook, where you would normally run the gatsby build command. Drupal isn’t available until after the deploy hook. So the Gatsby build is postponed until the post_deploy hook.

  To run gatsby build on-demand, or to trigger a rebuild from the backend when content is updated, define a runtime operation.

• mounts

  There are consequences to postponing the Gatsby build, as you don’t generally have write access to the container this late in the pipeline. To allow Gatsby to write to public, that directory has been defined as a mount.

Additionally, there has been a change to Gatsby’s start command,web.commands.start. In the generic Gatsby template, the static files in public are served via the web.locations block, but that attribute is removed in the file below. Instead, two separate start commands are defined depending on which branch you are developing on. This has been included to support Live Preview and Incremental Builds. It isn’t required, but you can consult the section below for more information about enabling it.

You can then modify gatsby-config.js to read from the backend Drupal container through the drupal relationship defined above to configure the baseUrl attribute for gatsby-source-drupal.

This is facilitated by Platform.sh’s Config Reader library. So be sure to install this to the Gatsby dependencies first when replicating. When used, Gatsby pulls the information to communicate with the Drupal container on the current branch.

Lastly, the Gatsby app itself needs to include GraphQL queries to handle the data coming from Drupal and create content pages. The most important files in the template you should consult are:

• gatsby/gatsby-node.js

  Dynamically creates individual pages from the data source using Gatsby’s Node API. It retrieves all of Drupal’s articles (see post-install below) using the GraphQL query allNodeArticle. A page is created (createPage) with formatting described by the template file article.js below (component). A path is also defined for each article, in this case using an alias you will define within Drupal using the Pathauto module.

• gatsby/src/templates/article.js

  The template file that defines how a single Drupal article should be formatted on Gatsby, retrieving the data from that article using the nodeArticle GraphQL query.

• gatsby/src/pages/articles.js

  Generates previews of articles at /articles on the Gatsby site using the allNodeArticle GraphQL query.

Deploy and post-install

Next steps

With Gatsby now deployed and pulling content from a backend Drupal application, there are a few things you may wish to change about your project going forward.

Shared application configuration

You can optionally combine the application configuration (.platform/services.yaml) for Gatsby and Drupal into a single configuration file. Like .platform/services.yaml and .platform/routes.yaml, this file is shared across the project and resides in the .platform subdirectory. You need to explicitly define the source of each application.

Multiple content sources

Gatsby supports pulling multiple sources into its build. This includes external services like Stripe and additional backend CMSs for different sets of content. As in this example with Drupal, you can branch off your repository and add an additional directory that contains the codebase for another backend. Then add the source plugin for that backend to gatsby-config.js.

Plan size

As mentioned previously, you should have at least a Medium plan for your multi-app projects. This size gives the project enough resources for all of your containers as well as the memory necessary to actually pull content from Drupal into Gatsby during its build.

Keep in mind that the increased plan size applies only to your production environment, and not to preview environments (which default to Standard ). As you continue to work with Gatsby and a backend headless CMS, you may want to upsize your preview environments.

Live preview and incremental builds

If you replicate the web.commands.start block in Gatsby’s .platform.app.yaml file above, you can enable incremental builds on your projects. Once you save an update to a piece of Drupal content on a preview branch, Drupal places a request to a dedicated /__refresh endpoint on Gatsby. Since Gatsby is running a development server on this non-production environment, this call causes Gatsby to retrieve content from Drupal once again, resulting in a near instantly updated article on the frontend.

To see how to enable this feature, consult the template’s README.