Registry /
aws / serverless-appsync-plugin
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
serverless-appsync-plugin
✓ plugins:
- serverless-appsync-plugin
✗ import * as AppSyncPlugin from 'serverless-appsync-plugin';
const AppSyncPlugin = require('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.
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;
serverless --version
Debug
Known issues
breakingUpgrading 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.fixConsult 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.
affects: <2.0.0
gotchaThe plugin requires Node.js v16 or higher. Using older Node.js versions will lead to installation and runtime errors.fixUpgrade your Node.js environment to version 16 or newer (e.g., `nvm install 18 && nvm use 18`).
affects: <2.0.0
gotchaThis 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.fixEnsure 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.
affects: <2.8.0 for Serverless v4, <2.0.0 for Serverless v3
deprecatedAs 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.fixConsider 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.
affects: >=4.0.0 (for Serverless Framework)
Errors
Common errors & fixes
Error: Plugin "serverless-appsync-plugin" not found.
The plugin has not been installed or is not correctly listed in the `plugins` section of your `serverless.yml` or `serverless.ts` file.
fixRun `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.
Your `appSync` configuration is missing the `schema` property, which specifies the path to your GraphQL schema file.
fixAdd `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.
A resolver specifies a `dataSource` that does not exist or is misspelled in the `appSync.dataSources` section.
fixVerify 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.
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.
fixEnsure 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.
Audit
Dependencies
serverlessrequiredRequired peer dependency for the plugin to integrate with and extend the Serverless Framework CLI and deployment lifecycle.