FutureStack 2022: Recapping our product announcements. Read our blog.

How to optimize build times for Gatsby apps

Published 7 min read

Gatsby enables developers to build fast, secure, and powerful websites using a React-based framework and data layer that simplifies integrating different content, APIs, and services into one web experience. Popular with developers who build and deploy websites using the Jamstack architecture (JavaScript, APIs, and markup), Gatsby builds your site as static files to be deployed to a content delivery network (CDN), improving page load times and reducing operational complexity. 

Now you can use New Relic to understand which APIs, plugins, or code changes are affecting build times for your website with a new Gatsby quickstart on New Relic Instant Observability. The quickstart hooks into the internal APIs of the Gatsby framework and provides granular build data directly in New Relic so you can debug and optimize your build times. This blog post walks through some best practices for measuring the performance of a large Gatsby site, which you can try out for yourself in a New Relic forever free account.

gatsby logo
Start monitoring your Gatsby data today.
Install the Gatsby quickstart Install the Gatsby quickstart

Gatsby build times for the massive New Relic Docs site

At New Relic, we are avid Gatsby users. Combining the functionality from React, GraphQL, and webpack, Gatsby’s open source framework allows New Relic’s documentation site to serve prebuilt files over a CDN, enabling better performance, higher security, easier scaling, and a better development experience.

We needed better insight and efficiency into the performance of our docs.newrelic.com site, one of the larger Gatsby sites in the world, with more than 8,000 Markdown files and an average of more than 30 content changes a day. Ruairi Douglas from the Developer Enablement team at New Relic and I collaborated to create the Gatsby Build quickstart, bringing the powers of instant observability into the entire Gatsby build process and exporting vital telemetry data from within the belly of the beast. With events, metrics, logs, and traces, we can now contextualize and identify performance issues within our website plugins, third-party APIs, and other parts of our website. 

We show some examples of what we found with docs.newrelic.com. You can use these examples as best practices for measuring performance of your own Gatsby builds.

Because of the massive amount of Markdown files and daily content changes, the docs.newrelic.com site has an average build time of about 45 minutes. For our engineers and open source contributors, reducing build times leads to faster iterations and more time to focus on code, rather than waiting on builds. To make the development process more efficient, our quickstart helps us understand which APIs, plugins, or code changes affect build times for our website.

How to use the Gatsby plugin to analyze build processes

To try out this plugin yourself, complete the following steps or watch the video:

1. Run the following command in the directory containing your Gatsby site:

npm i gatsby-build-newrelic.

2. Log in to New Relic One. If you don't already have an account, you can sign up for a forever free account.

3. Configure your Gatsby plugin in gatsby-config.js with the following code snippet:


  resolve: "gatsby-build-newrelic",
      options: {
        NR_INSERT_KEY: process.env.NEW_RELIC_INSERT_KEY || '',
        NR_LICENSE_KEY: process.env.NEW_RELIC_LICENSE_KEY || '',
        NR_ACCOUNT_ID: process.env.NEW_RELIC_ACCOUNT_ID,
        SITE_NAME: 'jankstack',
        customTags: { gatsbySite: true }

4. In package.json, change the build command to:
gatsby build --open-tracing-config-file ./node_modules/gatsby-build-newrelic/zipkin-local.js --graphql-tracing",

5. Run a Gatsby build with the following command:
npm run build

Track the impact of each plugin 

As your website grows, the number of plugins for customizations you need also increases. For example, from data source plugins to SEO and analytics plugins, the New Relic docs site relies on more than 100 plugins to serve our web pages. With the addition of each plugin, it becomes difficult to keep track of the impact each one has on the efficiency of the entire website.

The quickstart examines traces from Gatsby and analyzes the duration of plugins during the build process so you can see how much each plugin contributes to the overall build. You can see a dashboard like this one:

For example, the New Relic documentation website uses MDX, a flavor of markdown, to store the content. In the build process, it accounts for more than 75% of the build time of all of the website plugins. Even a small change in the efficiency of this plugin can shave dozens of minutes from the build process.

The newest version of MDX and gatsby-source-mdx introduces significant performance improvements by removing @babel/generator. This pull request has reduced the build time by 14%.

By observing the amount of time spent by each plugin, you can analyze where to improve efficiency. By removing @babel/generator, we reduced build times by 25% for the New Relic docs website:

Determine which cloud provider gives you the optimal build

In April, our Developer Enablement team officially opened a ticket to consider migrating our docs site from another provider to Gatsby Cloud because build times were slow, and build and deploy times were very unpredictable. Before the team could officially consider moving to Gatsby Cloud, they needed to evaluate the plan.

The Gatsby Build quickstart we created can provide essential benchmark measurements so you can determine which cloud provider will give you the optimal, most efficient builds. In addition, it can deploy previews of your website. 

View page creation time

To create a page, Gatsby synthesizes data sources through GraphQL APIs and combines it with styling. For most websites, creating pages takes at most about 1 to 2 seconds per 10k pages. However, some sites take anywhere from 30 seconds to many minutes to create one page. This delay almost always happens because the GraphQL query in the createPages API includes many fields that aren’t needed to create the pages. Most sites only need to query for the node ID in createPages. All other fields needed for the page should be queried in the page component’s query.

You can use the Gatsby Build quickstart to measure how long the createPages API takes for your build, which can be a great indicator for possible optimizations to build times:

Get an image audit

Image processing through gatsby-plugin-image and other plugins can take a long time, especially if you have a large number of images. If image processing takes up a large proportion of your build time, you can use the Gatsby Build quickstart to help you keep track of the number of images you have on your image, broken down by file type. This way, you can correlate the number of images you have with the overall build time. 

By accounting for the number of images you have in your website and correlating that with its contribution to build time, you can make informed decisions about:

  • Adding image pre-optimization into your website 
  • Using and evaluating digital asset managers
  • Using parallel image processing

Here’s an example of what we saw for docs.newrelic.com: