Gatsby Adapters: Making It Easier to Host Gatsby on Any Platform

Marc Littlemore
Marc Littlemore
August 24th, 2023

In the beginning, Gatsby was just a Static Site Generation but now it’s a Reactive Site Generator that offers features like Deferred Static Generation, Server-Side Rendering, or serverless functions. These additional features require more glue code on deployment platforms and for self-hosting Gatsby. In the past, plugins had to work around missing features or reach into Gatsby’s internals.

Luckily, these problems are now in the past as today we’re happy to introduce Gatsby Adapters!

Adapters are responsible for taking the production output from Gatsby and turning it into something your deployment platform understands. We want to make it easier to deploy and host Gatsby on your preferred platform and Gatsby Adapters are a huge step towards that goal. But there’s still lots more to do. As Netlify’s Director of Engineering, Claire Knight, wrote in Taking Gatsby to New Heights: Embracing Adaptability and Openness we want to give you the power of Adapters, enabling seamless integrations between Gatsby and other platforms.

Update gatsby to 5.12.0 (e.g. by running npm install gatsby@latest) and you can use and write Gatsby Adapters.

Getting started

By default, Gatsby will have a manifest of popular adapters it’ll reference during a build. This enables zero-configuration deployments on those deployment platforms. For these zero-configuration deployments, no manual user interaction is needed (e.g. no installation/usage of an “auto” package).

For example, on Netlify gatsby will automatically install gatsby-adapter-netlify. You can manually install it inside your dependencies if you want to skip the auto-install on each build. The adapter will then set up everything needed to host Gatsby on Netlify.

If you want to use an adapter that is not part of Gatsby’s manifest, you can install it into your dependencies and add it to your gatsby-config like so:

As part of the work on Gatsby Adapters, you’re now also able to define custom HTTP headers inside gatsby-config:

Gatsby passes all the required information during the build to Adapters to prepare these outputs for deployment on a specific platform. Here are some of the actions an Adapter automatically takes:

  • Applies HTTP headers to assets
  • Applies redirects and rewrites. The adapter can also create its own redirects or rewrites if necessary, for example, to map serverless functions to internal URLs.
  • Wraps serverless functions coming from Gatsby with platform-specific code (if necessary). Gatsby will produce Express-like handlers.
  • Apply trailing slash behavior and path prefix to URLs
  • Possibly uploads assets to CDN

Learn more

Gatsby Adapters are a great addition to the framework and a powerful feature. We have prepared a couple of new documentation pages for you to explain Gatsby Adapters in-depth. Check out these resources:

Also, check out the source code for gatsby-adapter-netlify and the initial RFC to see what a fully-featured adapter can look like and how the feature came to be.

What’s next for the Gatsby ecosystem?

Gatsby Adapters are just part of our vision for the Gatsby framework to have a great future not just at Netlify, but also out in the wider world of web development. We have lots more that we’re eager to bring to life, some of which are designed to make not just Gatsby, but other frameworks more powerful and efficient on Netlify.

As we balance our work across the Gatsby framework and other parts of its platform and ecosystem and reinforce its future, rest assured that as a vital tool for so many business and organisations, Gatsby’s health and prosperity is important to us, and we’re excited about it.

Talk to our team of Gatsby Experts to supercharge your website performance.