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

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:

gatsby-config.ts

Copygatsby-config.ts: copy code to clipboardimport type { GatsbyConfig } from "gatsby"import adapter from "gatsby-adapter-name"
const config: GatsbyConfig = {  adapter: adapter(),}
export default config

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

gatsby-config.ts

Copygatsby-config.ts: copy code to clipboardimport type { GatsbyConfig } from "gatsby"
const config: GatsbyConfig = {  headers: [    {      source: "/some-path",      headers: [        {          key: "x-custom-header",          value: "hello world"        }      ]    }  ]}
export default 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:

• Adapters Overview: Learn how to find and use adapters.
• Zero-Configuration Deployments: List of supported deployment platforms and how you can configure their adapters.
• Creating an Adapter: You can build your own! Start to finish guide on how to create and publish an adapter.
• HTTP Headers: As part of the Gatsby Adapters work you can now also specify HTTP headers for a given path.

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.