How to Configure Gatsby Adapters for Netlify, Vercel, and AWS Deployments

Gatsby adapters are plugin-like modules introduced in Gatsby 5.12 that transform static and server-rendered output into platform-specific formats, enabling zero-configuration deployments on Netlify while allowing custom implementations for AWS and other targets.

Gatsby adapters streamline the deployment process by automatically configuring platform-specific optimizations for your static site. Introduced in the gatsbyjs/gatsby repository as part of version 5.12, these adapters detect your hosting environment and transform build outputs to match platform requirements without manual configuration.

What Are Gatsby Adapters?

Adapters act as a small plug-in-like layer that takes the static and server-rendered output produced by Gatsby and transforms it into the format expected by a specific hosting platform. During the build process, Gatsby detects which platform you are deploying to, installs the appropriate adapter if it isn’t already a dependency, and runs the adapter’s adapt routine.

This routine can perform several platform-specific tasks:

• Write platform-specific headers and redirects
• Wrap serverless functions with the platform’s handler signature
• Upload assets to a CDN or inject CDN-aware URLs
• Apply trailing-slash and path-prefix rules

The adapter mechanism is part of Gatsby’s zero-configuration deployments feature. Gatsby will automatically pick an adapter based on environment variables, but you can also configure one manually in gatsby-config.js.

How Gatsby Adapters Work

The adapter system follows a detection and initialization pipeline defined in the core Gatsby package.

Adapter Detection Logic

The detection logic lives in the adapter manifest at packages/gatsby/adapters.js. This manifest lists adapters with a test function that inspects environment variables. For example, the Netlify adapter checks process.env.NETLIFY. The first adapter whose test returns true is selected automatically.

If no test matches, Gatsby falls back to a manual configuration or aborts with a helpful error message prompting you to configure an adapter explicitly.

Adapter Initialization

When the build starts, Gatsby runs src/utils/adapter/init.ts. This module loads the selected adapter module, verifies version compatibility with the current Gatsby version using the versions field from the manifest, and then calls the adapter’s adapt entry point to execute platform-specific transformations.

Configuring Gatsby Adapters for Specific Platforms

Netlify

The Netlify adapter is the only first-party adapter shipped with Gatsby. Its implementation lives under packages/gatsby-adapter-netlify and handles Netlify-specific optimizations automatically.

Key responsibilities include:

• Adding Netlify-specific redirect rules directly into netlify.toml (or creating the file if missing)
• Wrapping function bundles with Netlify’s handler signature via src/lambda-handler.ts
• Inserting marker comments (# gatsby-adapter-netlify start/end) into redirect files via src/route-handler.ts

Manual Configuration Example

While Gatsby auto-detects Netlify via environment variables, you can configure the adapter explicitly:

// gatsby-config.js
const netlifyAdapter = require("gatsby-adapter-netlify").default

module.exports = {
  siteMetadata: { title: "My Site" },
  plugins: [/* ... */],
  adapter: netlifyAdapter({
    // Optional: exclude datastore from engine function for smaller bundles
    excludeDatastoreFromEngineFunction: true,
  })
}

When you push to Netlify or run gatsby build locally with the NETLIFY environment variable set, Gatsby executes the Netlify-specific adaptation steps defined in packages/gatsby-adapter-netlify/src/index.ts.

Vercel

Vercel supports Gatsby out-of-the-box using generic framework detection. Because Gatsby’s build output already matches Vercel’s expectations—static files in public/ and serverless functions in functions/—you do not need a custom adapter.

Deployment Workflow

1. Deploy via Vercel for Git: Connect your repository, and Vercel automatically runs npm install && npm run build.
2. Or use the Vercel CLI:

vercel --prod

If you require platform-specific features like custom headers or redirects, you can either create a custom adapter following the Netlify adapter pattern, or use Vercel’s vercel.json configuration file alongside your standard Gatsby build.

AWS

Gatsby does not ship an AWS-specific adapter, but the adapter architecture supports custom implementations for AWS Amplify, S3 with CloudFront, or Lambda deployments.

A typical AWS deployment involves:

• Static hosting: Uploading the public/ directory to an S3 bucket and configuring CloudFront
• Serverless functions: Packaging SSR/DSG functions as Lambda@Edge or API Gateway handlers

Custom Adapter Skeleton

A custom adapter implements the adapt method to handle AWS-specific deployment logic:

// packages/gatsby-adapter-aws/src/index.ts
exports.name = "gatsby-adapter-aws"

exports.test = () => !!process.env.AWS_REGION

exports.adapt = async ({ publicDir, functionsDir, reporter }) => {
  // 1. Upload static assets to S3
  await uploadToS3(publicDir)
  
  // 2. Deploy functions as Lambda
  await deployLambdas(functionsDir)
  
  reporter.info("✅ Gatsby site deployed to AWS")
}

After publishing the package to npm (e.g., gatsby-adapter-aws), configure it in your project:

// gatsby-config.js
const awsAdapter = require("gatsby-adapter-aws").default

module.exports = {
  adapter: awsAdapter(),
}

You can use the Netlify adapter source code at packages/gatsby-adapter-netlify as a reference implementation for handling function bundling and platform-specific configuration files.

Summary

• Gatsby adapters are plugin-like modules introduced in version 5.12 that transform build output for specific hosting platforms.
• The adapter manifest at packages/gatsby/adapters.js handles automatic detection via environment variables like NETLIFY.
• Netlify is the only officially supported adapter, located at packages/gatsby-adapter-netlify, handling redirects, headers, and lambda wrapping automatically.
• Vercel requires no adapter because Gatsby’s default output structure matches Vercel’s expectations.
• AWS and other platforms require custom adapters implementing the adapt function, using the Netlify adapter as a template.

Frequently Asked Questions

What version of Gatsby introduced adapters?

Adapters were introduced in Gatsby 5.12 as part of the zero-configuration deployments feature. This version added the adapter manifest and automatic detection logic in packages/gatsby/adapters.js.

Do I need to manually install the Netlify adapter?

No. When Gatsby detects it is building on Netlify (via the NETLIFY environment variable), it automatically installs gatsby-adapter-netlify if not present in your dependencies. However, manually installing and configuring it in gatsby-config.js allows you to pass specific options like excludeDatastoreFromEngineFunction.

Why doesn't Vercel need a Gatsby adapter?

Vercel uses generic framework detection that recognizes Gatsby’s build output structure automatically. Since Gatsby places static files in public/ and serverless functions in functions/ by default, Vercel can deploy these without platform-specific transformation. This contrasts with Netlify, which requires specific redirect rule formatting and lambda handler wrapping.

How do I create a custom adapter for AWS or other platforms?

Create an npm package that exports a name, test function (returning boolean based on environment detection), and an adapt async function receiving publicDir, functionsDir, and reporter arguments. Use the Netlify adapter source at packages/gatsby-adapter-netlify as a reference for handling function bundling and platform configuration.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}