Creating an Adapter
If an adapter for your preferred deployment platform doesn’t exist yet, you can build your own. While the specifics of the adapter depend on the deployment platform and its requirements, the initial setup is the same for every adapter.
By the end of this guide you should be able to create and publish an adapter.
The adapters feature was added in
An adapter’s entry point should have the following API:
Gatsby makes a
AdapterInit type available that you can use to author your adapter. It also accepts a generic for the adapter options:
You can find all TypeScript types on GitHub.
The adapter should export a function as a default export with these object keys:
name: Unique name of the adapter. Please follow the naming convention
@scope/gatsby-adapter-<name>to make it easier for people to discover your adapter.
cache(Optional): Both handlers receive
directorieswhich are the directories that should be cached/restored for a build and the
restore: Hook to restore
directoriesfrom previous builds. Executed very early on in the build process. If the hook returns
false, Gatsby will skip cache restoration.
store: Hook to store
directoriesfor the current build. Executed as one of the last steps in the build process.
adapt: Hook to take Gatsby’s output and prepare it for deployment on the adapter’s platform. Executed as one of the last steps in the build process. Details on the inputs are documented below.
config(Optional): Hook to pass information from the adapter to Gatsby so it can adjust its build process. Details on the required output is documented below.
If your adapter accepts custom options, consider setting default values to make the adapter easier to use.
adapt receive the
reporter instance, so you can output structured logs to the user’s terminal. However, please don’t overdo it and keep the output to a minimum. If a user requires more details, they can always use the CLI with the
--verbose flag to get information about the adapter and logs for debugging.
adapt hook takes Gatsby’s output and prepares it for deployment on the adapter’s platform. It receives the following inputs:
routesManifest: Array of objects with three different types:
redirect. Each object contains all necessary information to deploy and apply these routes.
staticroutes will have default
headersapplied, which users can extend or overwrite with the HTTP headers option inside
gatsby-config. Routes will also have the
trailingSlashoption applied to their paths.
functionsManifest: Array of objects containing each function’s entry point and required files.
pathPrefix: Value of the
trailingSlash: Value of the
You can find the TypeScript types for these inputs on on GitHub.
adapt hook should do the following things:
- Apply HTTP headers to assets
- Apply redirects and rewrites. The adapter can also create its own redirects and rewrites, if necessary (e.g. mapping serverless functions to internal URLs).
- Wrap 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 upload assets to CDN
config hook is useful for passing information from an adapter back to Gatsby. This optional hook can enable advanced features of adapters to e.g. workaround platform limitations. It can also warn users against using features that an adapter doesn’s currently support and would cause faulty deployments.
config hook has to return an object with the following keys:
deployURL(Optional): URL representing the unique URL for an individual deploy
true, Gatsby will not include the LMDB datastore in the serverless functions used for SSR/DSG. Instead, it will place the LMDB datastore into the
publicfolder and later try to download the datastore from the given
supports(Optional): Describe which features an adapters supports
false, Gatsby will fail the build if user tries to use pathPrefix
trailingSlash(Optional): Provide an array of supported
pluginsToDisable(Optional): Provide an array of plugin names that should be disabled when adapter is used. Purpose of this is to disable any potential plugins that serve similar role as adapter that would cause conflicts when both plugin and adapter is used at the same time.
If you want to quickly prototype an adapter, you can also author your file(s) directly in an example project (before moving them to their own repository). Here’s how:
Create an adapter file called
gatsby-adapter-foo.jsat the root of your project:
Import the adapter file into your
Once it works, don’t forget to publish your adapter so that the community can benefit from it.
You can copy Gatsby’s complete adapter end-to-end testing suite and use it for your own adapter.
Before you publish, keep in mind that once people start using your adapter, you’ll need to make changes responsibly (following semver) and potentially automate some of the maintenance work.
We recommend that you follow this checklist before you publish your adapter for the first time:
Choose a clear name for your adapter following this naming convention:
To publish the adapter under a scope, follow this naming convention:
READMEshould explain to the user in concise steps how to install, use, and configure your adapter (also see How to write a plugin README). The
READMEwill be the first thing a user reviews so make sure that it’s accessible to everyone.
versionfield in your adapter’s
package.json. For future releases, follow semantic versioning.
keywordsfield in your adapter’s
gatsby-adapter. This way the adapter can be found through the plugin library.
peerDependenciesfield in your adapter’s
package.json, containing the
gatsbyversion range that your adapter is compatible with.
For example, if your adapter supports Gatsby 5 only (e.g. it uses an API only available in Gatsby 5), use:
If Gatsby releases a new major version and your adapter doesn’t require the new changes, you can mark your adapter as compatible with specific versions. For example, to mark your adapter as compatible with Gatsby 5 and Gatsby 6:
buildscript to your adapter’s
buildscript should compile your source code to CommonJS (CJS) into a
distfolder. If you’re authoring the code in TypeScript, also consider generating type definitions. If you’re authoring the code in CJS already there is no need for a
Since your compiled information will be in the
distfolder, you need to also add a
fileskey to the
If you’ve generated TypeScript types, consider adding a
preparescript to your adapter’s
package.jsonthat runs before
npm publish. If the
buildscript doesn’t automatically clear the
distfolder before a new build, add an additional
cleanscript. This ensures that old artifacts aren’t accidentally published. For example, if you rename a file and don’t run
clean, the old file will still be published through
dist. You could use del-cli to achieve this. It would look something like this:
Follow the other recommendations from npm’s Creating a package.json file documentation, e.g. adding a