Gatsby multi-app projects


A common pattern for Gatsby sites is to decouple services from the main site, pulling in external data at build time. Supported by Gatsby’s source plugin ecosystem, data from conventional (or headless) content management systems can be collected into a common Data Layer, with that CMS typically located on a server elsewhere, and that data then used to fill out content on the frontend.

The location of an external CMS is usually hardcoded into Gatsby’s configuration, so when you’re developing your site every branch points to the same backend resource. Should the location of that resource change, you would need to commit the new URL to update the configuration.

The decoupled pattern can work differently on due to support for multi-app configuration on your projects. Consider the following project structure:

├── .platform
│   ├── routes.yaml
│   └── services.yaml
├── drupal
│   ├── <application code>
│   └──
├── gatsby
│   ├── <application code>
│   └──

Above is the repository structure for a Decoupled Drupal (Gatsby sourcing Drupal content) project on Here, Gatsby and Drupal reside in their own subdirectories within the same repository. They are deployed to the same project from separate application containers, and from this cluster Gatsby can read data from Drupal internally. Their commit histories are tied together, such that each new pull request environment can test changes to either the frontend or backend freely from the same place.

Drupal is just one example of a backend CMS that can be used with this pattern, and at the bottom of this page are a few additional guides for alternatives that work well on


Next, you’re going to need a couple tools to be able to interact with your project, two of which you likely already have.

The first is Git, which you need to have installed before moving forward. As a Platform as a Service (PaaS), automatically manages everything your application needs in order to run. Git is the primary tool used to do this. Every commit pushed results in a new deployment, and all of your configuration is driven almost entirely by a small number of YAML files in your Git repository (which we will get to in the steps below). Your infrastructure, described in these files, becomes part of your application itself - completely transparent and version-controlled. If you do not already have Git on your computer, you should install it now.

Second, in this guide you interact with your project from both your browser and the command line using the CLI. Both utilize our API so that you can make changes to your projects, but the CLI will be the tool you use the most in this guide. Below are a set of installation commands for different operating systems:

# Linux/macOS
$ curl -sS | php
# Windows
$ curl -o cli-installer.php
$ php cli-installer.php

Once the installation has completed, you can run the CLI in your terminal with the command:

# Verify the installation
$ platform

On the first run, you need to log in using a browser.

Take a moment to view some of the available commands with the command:

# View the list of CLI commands
$ platform list

Signing up for 

In each of the backend guides below, there will be a “Deploy on” button that will not only deploy the guide’s project for you, but also sign you up for a trial account. If you are planning on simply deploying a template and following along with these guides for greater context, feel free to move onto the next section.

If however you are planning on using the templates and guides to deploy your existing codebase to, you will first need to visit the accounts page and fill out your information to set up your trial account. If you don’t want to sign up initially with your e-mail address, you can sign up using an existing GitHub, Bitbucket, or Google account. If you choose one of these options, you will be able to set a password for your account later.

After creating an account, you will be prompted to create your first project. Since you’ll be providing your own code, use the “Blank project” option. You will be able to give the project a title and choose a region closest to the visitors of your site. You also have the option to select more resources for your project. This is especially important with multi-application projects, so make sure to consult the Plan size note below for more details.

Plan size 

There are a few important points you will need to keep in mind when deploying this pattern if you have already deployed Gatsby by itself on, which are relevant to each backend example. After following the steps below, you may find that Gatsby fails to bundle assets during its build on projects of the “Development” plan size. This is a factor of both the size and number of Gatsby’s dependencies on the frontend, as well as the amount of data being pulled from the backend.

Multi-application projects generally require more resources to run on, and so the trial’s default development plan may not be enough to run your existing site. You are free to either proceed with a smaller plan to test or increase the resources at this point for the project. Otherwise, it may be best to initially deploy the templates listed in each backend guide to start out, and later modify that project to include your own code with more resources as you get used to developing on

Headless backends maintains a number of multi-application templates for Gatsby, that generally have very similar configuration changes on the Gatsby side. Below are a few of those written as short guides for different backend content management systems.