Serverless AppSync Plugin

2.10.5 · active · verified Sun Apr 19

The `serverless-appsync-plugin` extends the Serverless Framework to enable seamless deployment and management of AWS AppSync GraphQL APIs. Currently at stable version 2.10.5, the plugin receives regular updates, including bug fixes and new features, with several minor releases in late 2025. It differentiates itself by offering deep integration into the Serverless ecosystem, allowing developers to define AppSync schemas, data sources (Lambda, DynamoDB, HTTP, RDS, None), resolvers (VTL and JavaScript), authentication methods (API_KEY, AWS_IAM, AMAZON_COGNITO_USER_POOLS, OPENID_CONNECT), custom domains, caching, and Web Application Firewall (WAF) configurations directly within their `serverless.yml` or `serverless.ts` files. This declarative approach significantly simplifies the provisioning and updating of complex AppSync infrastructure, providing CLI commands and exposing CloudFormation variables for easy referencing of deployed resources.

Common errors

```
Error: Plugin "serverless-appsync-plugin" not found.
```
cause The plugin has not been installed or is not correctly listed in the `plugins` section of your `serverless.yml` or `serverless.ts` file.

fix Run `npm install serverless-appsync-plugin` or `yarn add serverless-appsync-plugin` and ensure it's listed under `plugins:` in your configuration.
```
AppSync validation failed: The 'schema' property is required.
```
cause Your `appSync` configuration is missing the `schema` property, which specifies the path to your GraphQL schema file.

fix Add `schema: schema.graphql` (or your actual schema file path) under the `appSync` block in your `serverless.yml` or `serverless.ts`.
```
Resolution of AppSync resources failed: dataSource for resolver 'Query.myField' not found.
```
cause A resolver specifies a `dataSource` that does not exist or is misspelled in the `appSync.dataSources` section.

fix Verify that the `dataSource` name referenced by your resolver (e.g., `Query.myField`) exactly matches a `name` defined within your `appSync.dataSources` array.
```
Cannot resolve variable at "provider.iam.role.statements.X.Resource.Fn::Sub": String value consist of variable which resolve with non-string value.
```
cause This typically occurs when trying to reference AppSync variables (like `appsync:arn`) within IAM policy resources, and the variable is not resolving correctly or is being used in an incompatible CloudFormation intrinsic function.

fix Ensure the AppSync API is deployed first so the variables can resolve. For IAM policies, use the `!GetAtt` CloudFormation intrinsic function to reference the `Arn` of the AppSync API resource directly if possible, or verify correct variable substitution syntax.

Warnings

breaking Upgrading from v1.x to v2.x involves significant breaking changes, including API configuration structure changes and dropped support for multiple AppSync APIs per stack. API keys may also be rotated on the first v2 deployment.
Fix: Consult the official 'Upgrading from v1' guide in the plugin's documentation. Ensure your `appSync` configuration is moved to the root level of `serverless.yml/ts` and adjust for single API definition. Backup and plan for API key rotation.
gotcha The plugin requires Node.js v16 or higher. Using older Node.js versions will lead to installation and runtime errors.
Fix: Upgrade your Node.js environment to version 16 or newer (e.g., `nvm install 18 && nvm use 18`).
gotcha This plugin has a peer dependency on Serverless Framework v3.0.0 or higher. While v2.8.0 introduced support for Serverless v4, older plugin versions (before v2.8.0) may not be compatible with Serverless v4, and no plugin version is compatible with Serverless v2.
Fix: Ensure your `serverless` dependency is `^3.0.0` or `^4.0.0` depending on your plugin version. For Serverless v4, use `serverless-appsync-plugin` v2.8.0 or newer.
deprecated As of Serverless Framework v4 (and potentially earlier versions with built-in AppSync support), the core framework now includes native AppSync integration. This means the `serverless-appsync-plugin` might no longer be strictly necessary and could potentially conflict with the built-in functionality.
Fix: Consider migrating to the native AppSync support within the Serverless Framework. Remove `serverless-appsync-plugin` from your `plugins` list and dependencies. The existing `appSync` configuration should largely remain compatible.

Install

npm install serverless-appsync-plugin npm
yarn add serverless-appsync-plugin yarn
pnpm add serverless-appsync-plugin pnpm

Imports

serverless-appsync-plugin
wrong:
```
import * as AppSyncPlugin from 'serverless-appsync-plugin';
const AppSyncPlugin = require('serverless-appsync-plugin');
```
correct:
```
plugins:
  - serverless-appsync-plugin
```
This package is a Serverless Framework plugin and is activated by listing its name in the 'plugins' section of your `serverless.yml` or `serverless.ts` configuration file. It does not export symbols for direct programmatic import into application code.
appSync Configuration Block
```
// in serverless.yml or serverless.ts
appSync:
  name: my-api
  authentication:
    type: API_KEY
  schema: schema.graphql
  # ... define dataSources, resolvers, etc.
```
The 'appSync' top-level property within your Serverless configuration file is where you define your AppSync API's name, authentication, schema path, data sources, resolvers, and other related settings. In v2, this block moved directly under the root of `serverless.yml` from `custom.appSync` in v1.
AppSync Exported Variables
```
provider:
  environment:
    APPSYNC_ID: ${appsync:id}
    APPSYNC_URL: ${appsync:url}
    APPSYNC_API_KEY: ${appsync:apiKey.myKey}
```
The plugin exports several variables (e.g., `id`, `url`, `arn`, `apiKey.[NAME]`) that can be referenced in your `serverless.yml` or `serverless.ts` for dynamic values generated during CloudFormation deployment.

Quickstart

This quickstart demonstrates a minimal Serverless.ts configuration using the plugin to deploy an AppSync API with an API key, a basic GraphQL schema, a Lambda data source, and a resolver. It sets up a 'hello' query backed by a Lambda function. To run this, you would also need a `schema.graphql` file and a `src/handlers/hello.handler` function.

import type { AWS } from '@serverless/typescript';

const serverlessConfiguration: AWS = {
  service: 'my-appsync-service',
  frameworkVersion: '3',
  plugins: [
    'serverless-appsync-plugin'
  ],
  provider: {
    name: 'aws',
    runtime: 'nodejs18.x',
    region: 'us-east-1',
    stage: 'dev',
    environment: {
      AWS_REGION: '${aws:region}',
    }
  },
  appSync: {
    name: '${self:service}-${sls:stage}-api',
    authentication: {
      type: 'API_KEY',
    },
    schema: 'schema.graphql', // Ensure this file exists at the root
    resolvers: {
      'Query.hello': {
        dataSource: 'helloLambda',
      },
    },
    dataSources: {
      helloLambda: {
        type: 'AWS_LAMBDA',
        config: {
          functionName: 'hello',
        },
      },
    },
    apiKeys: [
      {
        name: 'defaultApiKey',
      },
    ],
  },
  functions: {
    hello: {
      handler: 'src/handlers/hello.handler', // Ensure this file and handler exist
      events: [
        {
          http: {
            method: 'get',
            path: '/hello',
          },
        },
      ],
    },
  },
};

module.exports = serverlessConfiguration;

view raw JSON →