{"id":12010,"library":"serverless-appsync-plugin","title":"Serverless AppSync Plugin","description":"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.","status":"active","version":"2.10.5","language":"javascript","source_language":"en","source_url":"https://github.com/sid88in/serverless-appsync-plugin","tags":["javascript","typescript"],"install":[{"cmd":"npm install serverless-appsync-plugin","lang":"bash","label":"npm"},{"cmd":"yarn add serverless-appsync-plugin","lang":"bash","label":"yarn"},{"cmd":"pnpm add serverless-appsync-plugin","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required peer dependency for the plugin to integrate with and extend the Serverless Framework CLI and deployment lifecycle.","package":"serverless","optional":false}],"imports":[{"note":"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.","wrong":"import * as AppSyncPlugin from 'serverless-appsync-plugin';\nconst AppSyncPlugin = require('serverless-appsync-plugin');","symbol":"serverless-appsync-plugin","correct":"plugins:\n  - serverless-appsync-plugin"},{"note":"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.","symbol":"appSync Configuration Block","correct":"// in serverless.yml or serverless.ts\nappSync:\n  name: my-api\n  authentication:\n    type: API_KEY\n  schema: schema.graphql\n  # ... define dataSources, resolvers, etc."},{"note":"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.","symbol":"AppSync Exported Variables","correct":"provider:\n  environment:\n    APPSYNC_ID: ${appsync:id}\n    APPSYNC_URL: ${appsync:url}\n    APPSYNC_API_KEY: ${appsync:apiKey.myKey}"}],"quickstart":{"code":"import type { AWS } from '@serverless/typescript';\n\nconst serverlessConfiguration: AWS = {\n  service: 'my-appsync-service',\n  frameworkVersion: '3',\n  plugins: [\n    'serverless-appsync-plugin'\n  ],\n  provider: {\n    name: 'aws',\n    runtime: 'nodejs18.x',\n    region: 'us-east-1',\n    stage: 'dev',\n    environment: {\n      AWS_REGION: '${aws:region}',\n    }\n  },\n  appSync: {\n    name: '${self:service}-${sls:stage}-api',\n    authentication: {\n      type: 'API_KEY',\n    },\n    schema: 'schema.graphql', // Ensure this file exists at the root\n    resolvers: {\n      'Query.hello': {\n        dataSource: 'helloLambda',\n      },\n    },\n    dataSources: {\n      helloLambda: {\n        type: 'AWS_LAMBDA',\n        config: {\n          functionName: 'hello',\n        },\n      },\n    },\n    apiKeys: [\n      {\n        name: 'defaultApiKey',\n      },\n    ],\n  },\n  functions: {\n    hello: {\n      handler: 'src/handlers/hello.handler', // Ensure this file and handler exist\n      events: [\n        {\n          http: {\n            method: 'get',\n            path: '/hello',\n          },\n        },\n      ],\n    },\n  },\n};\n\nmodule.exports = serverlessConfiguration;","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"<2.0.0"},{"fix":"Upgrade your Node.js environment to version 16 or newer (e.g., `nvm install 18 && nvm use 18`).","message":"The plugin requires Node.js v16 or higher. Using older Node.js versions will lead to installation and runtime errors.","severity":"gotcha","affected_versions":"<2.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<2.8.0 for Serverless v4, <2.0.0 for Serverless v3"},{"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.","message":"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.","severity":"deprecated","affected_versions":">=4.0.0 (for Serverless Framework)"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Run `npm install serverless-appsync-plugin` or `yarn add serverless-appsync-plugin` and ensure it's listed under `plugins:` in your configuration.","cause":"The plugin has not been installed or is not correctly listed in the `plugins` section of your `serverless.yml` or `serverless.ts` file.","error":"Error: Plugin \"serverless-appsync-plugin\" not found."},{"fix":"Add `schema: schema.graphql` (or your actual schema file path) under the `appSync` block in your `serverless.yml` or `serverless.ts`.","cause":"Your `appSync` configuration is missing the `schema` property, which specifies the path to your GraphQL schema file.","error":"AppSync validation failed: The 'schema' property is required."},{"fix":"Verify that the `dataSource` name referenced by your resolver (e.g., `Query.myField`) exactly matches a `name` defined within your `appSync.dataSources` array.","cause":"A resolver specifies a `dataSource` that does not exist or is misspelled in the `appSync.dataSources` section.","error":"Resolution of AppSync resources failed: dataSource for resolver 'Query.myField' not found."},{"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.","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.","error":"Cannot resolve variable at \"provider.iam.role.statements.X.Resource.Fn::Sub\": String value consist of variable which resolve with non-string value."}],"ecosystem":"npm"}