2.x module setup guide

To integrate Gatsby.js with Drupal you will need to configure the Gatsby.js application, Drupal Gatsby module, and optionally Gatsby Cloud.

Gatsby Cloud Configuration (optional).

1. Set the preview environment variable under "Preview variables" in your Gatsby Cloud configuration. This will instruct the Gatsby.js application to build unpublished pages.

An example variable is GATSBY_IS_PREVIEW with the value of 'true.'

2. If you are using the key_auth module then you will want to add an API key variable as well (e.g. JSON_API_KEY).

3. Copy the Preview, Build, and Content Sync Webhook URLs for the Drupal module configuration.

Drupal Configuration

1. Download (using Composer) and enable the Gatsby module:
   composer require drupal/gatsby
drush en -y gatsby
2. Configure module settings at /admin/config/services/gatsby/settings:
   1. Gatsby Server URL
      1. Copy the URL you get from Gatsby Cloud (or your self-hosted server)
      2. For local development: http://localhost:8000/
   2. Preview Webhook URL(s)
      1. Copy the URL from Gatsby Cloud. Alternatively, you can provide your own trigger if you self-host.
      2. For local development
         1. Example if running Drupal in docker: http://host.docker.internal:8000/__refresh
         2. Add this to your .env.development file: ENABLE_GATSBY_REFRESH_ENDPOINT=true
   3. Build Webhook URL(s) - Copy this URL from Gatsby Cloud.
   4. Content Sync URL (Gatsby 4+) - Copy this URL from Gatsby Cloud. If not using your path alias will need to match the path in Gatsby for the preview to work.
   5. Only trigger builds for published content: This setting means that only entity types of "Node" will trigger preview/build updates. This currently presents a limitation if you have pathauto and/or redirects enabled as those corresponding entity types will NOT get triggered. Other entity types related through entity reference however will get included with the updated node.
   6. Entity types to send to Gatsby Preview and Build Server - You will want to add any entity here that is queried inside of the Gatsby application. If you do not select all entities, Preview might not show your changes. Recommended entities include: File, Media, Content, Taxonomy term, URL alias.
3. Enable the key_auth module. This module allows you to have an "API user" who can see unpublished or draft content.
   1. Download and enable the key_auth module:
      composer require drupal/key_auth
drush en -y key_auth
   2. Create an "API" user role in Drupal. This role will need to be able to view unpublished content.
   3. Add the "Use key authentication" permission to this new role.
4. Assign additional permissions:
   1. Add “Sync Gatsby Fastbuild log entities” to a role that can sync build logs (builds and preview will need this)
   2. Add “Sync Gatsby Fastbuild preview log entities” permission to a role that can sync preview log entities
   3. Add “View Gatsby log entity entities” to roles that can view logs (builds and preview will need this)
   4. Add “View all revisions” to a role that can view unpublished content
   5. Add “View any unpublished content” to a role that can view unpublished content
   6. Add “View the latest version” to a role that can view unpublished content
5. Configure the jsonapi_extras module.
   1. Note: This module should already be downloaded and enabled if you used Composer to install the Gatsby module.
   2. Configure settings:
      1. Go to /admin/config/services/jsonapi/extras and enable “Include count in collection queries” setting at to improve Gatsby build performance.
      2. Go to /admin/config/services/jsonapi/resource_types, disable endpoints that are not needed by the Gatsby application to improve performance. Disable fastbuilds log entities.

Gatsby Application

1. Configure .env variables.
   1. API variable (if key_auth is used)
   2. Preview variable that matches what is used in Gatsby Cloud (e.g. GATSBY_IS_PREVIEW)
2. Configure gatsby-config.js.
   1. Add “headers” option to gatsby-source-drupal configuration for preview user (if key_auth used):
      headers: {
'api-key': [API key variable]
}
   2. Add fastBuilds: true to gatsby-source-drupal configuration. Gatsby cloud updates will NOT work without this setting.
   3. For local development where Drupal is running a Docker container, you need to open a port when starting Gatsby for Drupal to communicate with. 
      1. In package.json, in the "scripts" section, change the "start" command to:
         "start": "gatsby develop -H 0.0.0.0"
      2. Instead of running "gatsby develop", run npm run start
      3. Now Gatsby is setup to receive live updates from your local Drupal server.
   4. Update gatsby-node.js. Typically you will want to use the preview variable in conditionals that involve createPage calls. This will ensure that the preview environment will create unpublished and draft pages.
   5. Add Schema snapshot plugin (optional). This plugin helps prevent errors related to Drupal schema changes.

Gatsby in a Docker container

If you are running Gatsby inside a Docker container, there are a few tweaks to your environment that need to be made in order for your site to run as expected in development mode.  

1. Expose a port for Internal Status Port e.g. 5001
2. Set the container environment variable INTERNAL_STATUS_PORT to this port e.g INTERNAL_STATUS_PORT=5001
3. Set the container environment variable CHOKIDAR_USEPOLLING=true
4. Run develop with the -h parameter gatsby develop -h 0.0.0.0
5. Set Webpack polling to time-based, not fsevents based in your gatsby-node.js:

exports.onCreateWebpackConfig = ({ actions }) => {
  actions.setWebpackConfig({
    watchOptions: {
      aggregateTimeout: 200,
      poll: 1000,
      ignored: '**/node_modules',
    },
  })
}

Further details as to why this is required and setting up in Docksal are available in this blog post.