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

> Learn how to configure Gatsby adapters for seamless Netlify, Vercel, and AWS deployments. Gatsby adapters transform your site's output for zero-config platform-specific builds.

- Repository: [Gatsby/gatsby](https://github.com/gatsbyjs/gatsby)
- Tags: how-to-guide
- Published: 2026-03-06

---

**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`](https://github.com/gatsbyjs/gatsby/blob/main/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`](https://github.com/gatsbyjs/gatsby/blob/main/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`](https://github.com/gatsbyjs/gatsby/blob/main/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`](https://github.com/gatsbyjs/gatsby/blob/main/netlify.toml) (or creating the file if missing)
- Wrapping function bundles with Netlify’s `handler` signature via [`src/lambda-handler.ts`](https://github.com/gatsbyjs/gatsby/blob/main/src/lambda-handler.ts)
- Inserting marker comments (`# gatsby-adapter-netlify start/end`) into redirect files via [`src/route-handler.ts`](https://github.com/gatsbyjs/gatsby/blob/main/src/route-handler.ts)

#### Manual Configuration Example

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

```javascript
// 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`](https://github.com/gatsbyjs/gatsby/blob/main/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**:

```bash
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`](https://github.com/gatsbyjs/gatsby/blob/main/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:

```javascript
// 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:

```javascript
// 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`](https://github.com/gatsbyjs/gatsby/blob/main/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`](https://github.com/gatsbyjs/gatsby/blob/main/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`](https://github.com/gatsbyjs/gatsby/blob/main/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.